Untitled

README FILE FOR PRODUCT Pro*C/C++ 8.0.4

----------------------------------------------------------

This file contains important information regarding Pro*C/C++ Version

8.0.4, which is the precompiler release corresponding to 8.0.4 Oracle

database. These notes are divided into four sections:

* Section 1 describes compatibility issues

* Section 2 briefly describes the new functionality introduced in this

release.

* Section 3 describes the bugs that are fixed in this release

* Section 4 lists known restrictions and bugs in Pro*C/++ 8.0.4. It also

provides some usage tips for the new host variable types introduced in

this release.

SECTION 1: Compatibility and Migration Issues

---------------------------------------------

Desupport Notification for V6 Compatibility Behavior

----------------------------------------------------

With Oracle7, Oracle offered a Version 6 [V6] Compatibility flag that allowed

application developers developing Oracle7 applications to emulate Oracle6

behavior. Beginning with the release of Oracle 8.0.3, users are cautioned that

the Version 6 compatibility flag is being desupported effective immediately in

all of the Oracle8 products including PL/SQL8, all the Oracle Precompilers,

the Oracle8 Oracle Call Interface, SQL*Module, and SQL*PLUS. The desupport of

the V6 compatibility flag is consistent with Oracle's policy of supporting

backwards compatibility and behavior from one version release upgrade to

another i.e. from Oracle6 to Oracle7 but not for more than one version release

upgrade.

Specifically, the V6 Compatibility flag emulated the following aspects of

Oracle6 behavior with Oracle7:

o String literals are fixed length in Oracle7 but are treated as variable

length with the V6 flag

o PL/SQL Local char variables are fixed length in Oracle7 but are treated

as variable length with the V6 flag

o Return value of SQL Functions (e.g. USER) are fixed length characters in

Oracle7 but are treated as variable length characters with the V6 flag

o Select/Fetch of a NULL with no indicator raises an ORA-1405 error with

Oracle7 but returns no error with the V6 flag

o SQL group function is called at FETCH time with Oracle7 but is called

query execution time with the V6 flag

o Describe of a fixed length string returns Type=96 with Oracle7 but

returns Type=1 with the V6 flag

All of these behaviors are being desupported with the desupport of the V6

Compatibility Flag with Oracle8.

SECTION 2: NEW FUNCTIONALITY

-----------------------------

1. New non-Object Functionality for version 8.0.4

a. Expiring Passwords

New syntax for updating passwords is accepted on the connection.

b. Arrays of Structs

Arrays of structs are now supported as host variables and indicator

variables.

c. BLOBs, CLOBs and National Character LOBs

Binary and Character LOBs (Large Objects) can be manipulated in

Pro*C/C++ via host variables of LOB locator types OCIBlobLocator* and

OCIClobLocator*. National Character LOBs are also supported.

d. Support for NCHAR data

NCHAR data is now fully supported by the kernel. Previous releases

of the precompiler supported this datatype with the NLS_LOCAL option.

For new applications, users are strongly encouraged to rely on the

database support and accordingly set NLS_LOCAL=NO during precompilation.

e. User Callable SQLLIB Functions

The existing user-callable sqllib functions have been given longer,

more descriptive names. For compatibility reasons, the old names

are still accepted. Users are strongly encouraged to use the new

names in all new applications.

f. User Settable Runtime Context Options

The runtime context has options which are set to default values when it

is created and allocated, A generic mechanism for setting specific

runtime context values has been introduced. Only a coupld of options

are currently supported, however.

g. New WHENEVER action 'DO CONTINUE'

The 'DO CONTINUE' action behaves much like a 'DO BREAK'. In the latter

case, an explicit 'break' statement is issued. The 'DO CONTINUE' action

causes a 'continue' statement to be generated. This differs from the

'CONTINUE' action which just results in the continuation of the program.

Please see user documentation on Pro*C/C++ Version 8.0.4 for further

details on these features.

2. New Object Functionality for Pro*C/C++ Version 8.0.4

a. Support For Object Types

Pro*C/C++ supports the manipulation of host variables of object types

via embedded SQL and PL/SQL statements. Users must run OTT (Object Type

Translator) to generate typedefs of C structs for named types defined

in the Oracle8 database, and declare variables of these types (or

pointers to these types) in the Pro*C/C++ application program to

correspond to object instances in the Oracle8 database.

b. Use of OTT-generated Type Files

An additional Pro*C/C++ input file, the INTYPE file, is specified

on the command-line to give the precompiler necessary information

about object types. This file is generated by OTT during translation

of object types in an Oracle8 database to typedefs of C structs.

c. Support for Navigational Operations

A Navigational Interface for providing operations for Creating Objects,

manipulating Object References, Setting and Getting Attributes of

Objects as well as controlling the Pinning and Unpinning of Objects in

the Object Cache are provided as part of the Pro*C/C++ 8.0.4 release.

NOTE: A ref needs to be allocated in all instances where it will be

returned. Specifically, in an exec sql object create with returning

ref call, the host variable following 'returning ref into' must

have contain a previously allocated ref (via exec sql allocate :hv).

Sample programs of new object functionality are located in

ORACLE_HOME\pro80\c\samples. Included are

o objdemo1 - Use of Object types in Pro*C/C++

o coldemo1 - Use of Collection types in Pro*C/C++

o lobdemo1 - Use of LOB types in Pro*C/C++

o navdemo1 - Use of the Navigational Interface in Pro*C/C++

3. Interoperation of Pro*C/C++ 8.0.4 programs with 8.0 OCI

a. New OCI Interoperability Functions

New library routines SQLEnvGet() and SQLSvcCtxGet() are introduced

to support interoperation of 8.0.4 Pro*C/C++ programs with 8.0 OCI.

The 8.0 OCI environment handle and the 8.0 OCI service context handle

for a database connection established in Pro*C/C++ may be obtained via

the above routines.

SECTION 3: Bugs fixed in this release

-------------------------------------

Bugs Fixed between Release 8.0.3 and Release 8.0.4

==================================================

552084 A failed attempt to logon to the database through Pro*C will

result in a shadow process being left in the server unkilled.

Subsequent failed attempts to logon will result in new shadow

processes being left until either the program itself is

terminated or the server runs out of processes.

546237 Can not connect to the database when using an explicit database

name associated with the username in a connect string. For

example, trying to connect as 'scott@remote' would fail with an

ORA-1017 error.

523931 The WHENEVER NOT FOUND condition was never checked after any of

the various INSERT statements. A PL/SQL trigger on an INSERT

statement that returned NO DATA FOUND would not be trapped by a

WHENEVER NOT FOUND condition for example.

515582 Pro*C would dump core whenever a string literal was used as a

bind variable expression. For example..

exec sql select job into :job from emp where ename = :"KING";

Use of string literals as bind expressions is ILLEGAL and will

now be flagged as an error by the precompiler.

509647 A core dump would result if the preceeding colon was missing on

an attribute in a Navigational OBJECT SET statement. This did

not occur on the OBJECT GET however.

508256 Processing a DEREF() or REF() in a query would cause Pro*C to dump

core depending on the platform.

506520 Pro*C would yield a syntactic error when a valid SQL hint was

used in an INSERT statement. Any valid hint would result in such

an error in any form of INSERT statement.

503981 Pro*C can not handle host arrays with dynamic sql method to execute

a pl/sql block correctly.

217428 Having two columns in a table of type VARCHAR2(2000) was being

incorrectly considered as two LONG columns which is not allowed.

This prevented applications from being developed using these

sizes for more than one VARCHAR2 column in a table.

286765 When binding host arrays to PL/SQL tables through dynamic SQL,

runtime errors would result.

Host arrays used in a dynamic sql method 2 EXEC SQL EXECUTE

statement may have two different interpretations based on the

presence or absence of the new optional keyword EXECUTE on an

ARRAYLEN statement.

Please refer to Programmer's Guide to the Oracle Pro*C/C++

Precompiler, Release 8.0.4 for more information.

Bugs Fixed between Release 2.2.3 and Release 8.0.3

==================================================

472139 Pro*C did not process equivalenced variable when parse != full

Pro*C would not process a datatype equivalenced variable when

the value of the parse option was not set to FULL. For example

typedef short *sb2ptr;

exec sql begin declare section;

exec sql type sb2ptr is integer(2) reference;

sb2ptr ind;

int x;

exec sql end declare section;

exec sql select comm into :x:ind where empno = ..;

The generated code would take the address of ind (&ind) rather

than reference ind directly since it really is a pointer. This

would happen when parse != full only.

471975 Possible read from freed memory using ORACA saved statement text

Precompiler applications that used the ORACA and requested the

statement text could encounter memory-related problems (e.g. core

dumps) when also using dynamic sql. This was particularly likely to

happen when the host variable used to hold the statement text pointed

to dynamically allocated memory that was subsequently freed or when

it was an automatic variable. A side-effect of this bug fix is that

sqlgls() no longer returns "old" statement text when called after

a statement that is parsed by the precompiler. For example:

exec sql declare c1 cursor for select ename from emp;

exec sql open c1;

sqlgls() /* Returns "select ename from emp" */

exec sql rollback work release;

sqlgls() /* This returns NO statement text */

471039 Pro*C did not handle SQL hints in DELETE statements correctly

Pro*C would rearrange the DELETE statement in such a way as to

prevent any SQL hint from being used. For example..

exec sql delete /*+ INDEX (emp emp_idx) */ from emp ..

=> "delete from /*+ INDEX (emp emp_idx) */ emp .."

Pro*C would displace the hint which would then result in it

not being used during statement execution.

465932 Pro*C did not allow solitary ' inside a #error directive

Pro*C would treat a single ' as the beginning of a SQL

string literal inside preprocessor directives.

#error This didn't work

Thus, Pro*C would give an error about an unterminated SQL

string when parsing the above #error directive.

443347 Prepare before executing dynamic array gets wrong results

When prepare of an insert statement to be used in a dynamic array

insert and then prepare another statement containing a PL/SQL block,

at execution it will only insert a single row.

414511 Pro*C did not allow spaces after line continuation in directives

Spaces appearing between a line continuation and the newline

character inside a preprocessor directive were not ignored by

Pro*C. For example

#define foo(a,b) a + \

b 123

1 line continuation

2 space(s)

3 newline (end of line)

This would result in precompile errors during the preprocessing

phase of precompilation. Pro*C now ignores these extra spaces.

408116 Pro*C core dumps if /*+ comment with Multi-Byte characters

Pro*C core dumps when /*+ comments contain Multi-Byte characters

because possibility of Multi-Byte characters wasn't considered.

406516 Long PCC-F-02135 messages on command line options get chopped off

If values of help options, such as the INCLUDE files, are very long

and the user asks to see a help message on such an option, only part

of the value would be shown, and in some cases a segfault would occur.

402136 ORA-1459 When inserting a NULL with a VARCHAR variable

The message ORA-1459:invalid length for variable character string

is returned when varchar pointers which point to zero-length

strings are inserted into the database.

400907 Option values longer than 80 characters cause precompiler to hang

When an option list is used, where the combined length of the list

values exceeds 80 characters, the precompiler will hang.

397811 Array size mismatch in Array DML with 'AT :database' clause

Pro*C would give an array size mismatch error on a DML statement

with host arrays (of equal dimension) when an 'AT :database'

clause was present. Note that the DBNAME in the AT clause was

itself a scalar host variable which was causing the mismatch.

397223 Cannot refer to a specific element of an undimensioned array

The problem was that when a specific element of an Undimensioned

array was used in an EXEC SQL statement as a Host variable, it gave

a Precompiler Error. Precompiler Error was generated to FIX the

coredump of 215929. With this FIX, it removes the Core dump, and

proceeds for correct precompilation and execution, without any

precompile.

382795 Pro*C can't parse "#define ident 'LOTTO'" directive

When user uses #define ident B, Pro*C flagged an error because of

ident, as a keyword was not allowed for #define. (To make a note that

ident is used as a keyword on some platforms). So, the gramamr rule

was changed to accomodate the use of "ident" same as other keywords

like if, ifdef, etc.

371255 Seg Fault when pointer is invalid but indicator is null

When a bind variable pointer is invalid and the associated

indicator is set to -1, an access violation occurs.

366775 Core dump precompiling with THREADS=YES - Temp files not deleted

Although, it's user's responsibility to write code needed for

threads=yes to work, it should NOT core dump. With this FIX, it

generates the semantic error message, and then tmp files are deleted.

For example, the following error message will be generated for the

testcase supplied with this bug:

(1) PCC-F-02390, No EXEC SQL CONTEXT USE statement encountered

359035 NLS: Column position is not correct when comment line is generated

When NLS char exist in a stream of chars, then due to multibyte

column count needed to be corrected. For example, if there are

45 chars in a stream, out of which 2 are NLS (multibyte), then

in reality there are only 43 chars. If 45 is used, then it will

fetch next 2 bytes, which might happen to be the beginning of

comment /*. This will mess up the whole comment structure. So

the number of correct char. counts is calculated with this fix.

345010 Pro*C could not handle use of the ANSI token merging operator

Using the merging operator '##' would cause Pro*C to generate

spurious syntactic error messages. The syntax is now accepted

but the merging is not done. Pro*C will accept the use of the

operator but will not support the functionality.

344346 Precompiler help screen loops infinitely for some NLS languages

When requesting the help screen, precompiler would loop infinitely

for certain NLS languages in which the description of the command

line option was excessively long, without intervening spaces so much

so that it could't fit on a single line without being broken up into

multiple lines.

268198 Pro*C did not allow split of EXEC SQL BEGIN/END DECLARE SECTION

Pro*C required that EXEC SQL BEGIN/END DECLARE SECTION be

written all on one line with the possibility of splitting it

across multiple lines. Syntactic errors would result otherwise.

479063 Spurious runtime errors when using arrays of LOB types

The precompiler produced incorrect code when processing certain

array declarations of LOB types, particularly when they appeared in

a function parameter list. For example, the following statement

was not precompiled correctly:

void BlobFunc(multi_blob)

OCIBlobLocator *multi_blob[];

475284 Pro*C dumped core after generating certain error messages

Pro*C would dump core after finding certain errors related to

the use of bind variables declared to be of some new Objects

related types (ie; OCINumber). This would also happen due to

the fact that an Objects program was being precompiled without

specifying an INTYPE file.

469671 Pro*C dumped core when processing long lines of Multibyte text

For excessively long lines of input having a lot of Multibyte

text, Pro*C would terminate abnormally with a core dump.

464714 The FIPS report showed all violations occured at line 0 (zero)

The FIPS report generated by Pro*C would indicate that all

violations occured at line 0 (zero) rather than the actual

source line in the program where the violation really occured.

463066 Pro*C did not allow C expressions in Equivalence statements

Pro*C did not allow complex precompile time evaluabe constant

expressions to be used in datatype equivalence statements.

#define LENGTH 10

char x[LENGTH+1];

exec sql var x is string(LENGTH + 1);

Pro*C now accepts any constant expression that can be

evaluated to a numeric value at precompile time in any SQL

datatype length specification for VAR/TYPE statements.

461907 Pro*C did not give an error for a LONG VARCHAR with missing length

The LONG VARCHAR datatype requires a length. Pro*C, however,

would accept a LONG VARCHAR without a length which would result in

a runtime error.

exec sql var foo is long varchar;

This is illegal. A syntactic error message is now generated.

454733 Pro*C/C++ didn't accept WITH clauses in any subquery

New with Oracle8 were the addition of WITH clauses in subqueries.

Pro*C didn't allow WITH clauses. Instead, syntactic errors would

result. The following was not accepted for example..

exec sql insert into (select ename, deptno from emp

where deptno > 10 with check option)

values ('Taylor', 20);

The 'with read only' clause would also not be accepted. The only

workaround was to use Dynamic SQL instead.

454727 Pro*C did not accept the PARTITION clause on a table name

Pro*C would reject syntactically the use of the PARTITION

clause on a table name in any DML statement. For example,

exec sql delete from sales partition (nov96) where ..

the only workaround was to use Dynamic SQL.

453328 Pro*C could not handle userid option if sqlcheck != full

Pro*C would not allow the use of the userid option if the

sqlcheck option was not set to full.

434744 Command-line options were not added to list file for ltype=long

When the ltype command-line option is set to long, the current

command-line option values should appear in the listing file.

Also, the formfeed character should appear between pages, but

not as the first character in the list file.

429924 Pro*C could not handle use of '&' in whenever statements

Pro*C would not allow use of the '&' operator in whenever

statements. For example..

exec sql whenever sqlerror do sql_error(&x);

An unintelligable error would result. Pro*C now accepts

this as a form of complex expression which it can now

handle better.

428633 Pro*C did not allow unary expressions in a WHENEVER statement

Pro*C would not allow a unary expression in a WHENEVER

statement. For example..

exec sql whenever sqlerror do sql_error(-1);

Now Pro*C will accept any unary expression. Binary expressions

are NOT supported in a WHENEVER statement currently, however.

426826 Pro*C dumped core if when allocating an undefined variable

Pro*C would dump core if an allocate of an undefined variable

was attempted. For example..

exec sql allocate :undefined;

Now a useful error is generated stating that both the variable

is undefined and that a type error occured on the allocate.

406664 Pro*C would not include a file whose name was a macro

Pro*C would only allow files defined by a macro to be

#included if code=ansi_c or cpp. Some kr_c compilers

allow this but Pro*C would yield syntactic errors.

#define HEADER "file.h"

#include HEADER

This worked when code=ansi_c or cpp, but not kr_c. No

real workaround since use of ansi_c generated code that

would not compile with a kr_c compiler.

399274 Pro*C sometimes switches the order of START WITH .. CONNECT BY

Originally, Pro*C would always generate 'START WITH' followed

'CONNECT BY' even if the 'CONNECT BY' appeared first. This

would cause problems if the statement was a prepared statement

subsequentally used with an explicit cursor. The resulting

'OPEN USING <bind variable list>' would hence sometimes result

in the bind variables being in the wrong order because the

statement was generated in the opposite order. This would cause

runtime type mismatch errors during execution of the program.

364746 Pro*C would not allow a <table>.* reference without a C++ error

Pro*C would give an error about using C++ punctuation even with

a legal <table>.* reference in a SQL statement. For example

exec sql select emp.* into :emp_struct from emp;

Workaround was to remove the 'emp.' and just do a 'select *'.

Note that the error only occured when precompiling with CODE=CPP.

SECTION 4: KNOWN RESTRICTIONS AND BUGS IN PRO*C/C++ 8.0.4

---------------------------------------------------------

1. #include vs EXEC SQL INCLUDE (Bug 450572)

Programs that include the Oracle header files such as sqlca.h or sqlda.h

using BOTH a #include and an explicit EXEC SQL INCLUDE will not precompile

correctly resulting in generated code that does not compile. The simplest

workaround is to just use a #include wherever possible, avoiding the use

of the older EXEC SQL INCLUDE syntax altogether.

2. New Datatypes

Below is a table which lists the known restrictions and bugs in the new

functionality introduced in Pro*C/C++ Version 8.0.4.

New C types PRO*C/C++ PRO*C/C++ PRO*C/C++

SUPPORT IN SUPPORT FOR SUPPORT IN

In Oracle8 EMBEDDED SQL BULK OPERATIONS *1 EMBEDDED PLSQL *2

---------------------------------------------------------------------------

OCINumber | yes | no | yes

OCIString | yes *3 | no | no

OCIRaw | yes | no | yes

OCIDate | yes | no | no

OCIRef *4 | yes | yes | no

OCIBlobLocator | yes | yes | yes

OCIClobLocator | yes *5 | yes *5 | yes *5

ADT's *6 | yes | yes | yes *7, *8

Nested Tables | yes | yes | yes

VARRAYS | yes | yes | yes

---------------------------------------------------------------------------

*1) This column refers to Pro*C/C++ support for multi-row (bulk) embedded

SQL operations with bind variables that are arrays of the given host

type.

*2) Arrays of new C types are not supported in PL/SQL blocks embedded within

Pro*C/C++.

*3) Host variables of type OCIString are supported only within ADTs. If a

character attribute of an object type is mapped by OTT to an OCIString

field in a C struct, then it can be used within Pro*C/C++ only in

operations that manipulate the object as a whole.

Use of such an OCIString field individually, as a stand-alone bind

variable (e.g., to bind to a column in a relational table) is currently

not supported.

*4) OCIRef host variables (representing REFs in the Oracle8 database) are

supported within embedded SQL and in the Pro*C/C++ mode SQLCHECK=SYNTAX.

However, OCIRef variables cannot be used in embedded PL/SQL blocks, or

with the Pro*C/C++ command line option SQLCHECK=FULL (or equivalently,

SEMANTICS).

A work-around is to always use SQLCHECK=SYNTAX for Pro*C/C++ program

modules that contain OCIRef variables. This may require a Pro*C/C++

application program to be modularized into multiple .pc files such that

a .pc file with a OCIRef variable does not contain any embedded PL/SQL

blocks (which are required to be precompiled with the option

SQLCHECK=FULL).

*5) National Character LOBs are also supported in 8.0.4.

*6) User defined named data types are not supported in dynamic SQL

Method 4.

*7) Selecting whole ADT instances from typed tables using the VALUE()

function on a table alias is not supported in embedded PL/SQL, or with

the Pro*C/C++ command line option SQLCHECK=FULL (or semantics).

*8) ADT attributes of type LOB cannot be manipulated in embedded PL/SQL.

A work-around is to use OCI routines to manipulate LOB attributes

embedded in ADTs.

3. Type Equivalencing Operations

Pro*C/C++ has never expanded macros used as type names in an EXEC SQL

TYPE directive. For example, the following would never have been

supported by any version of Pro*C/C++

#define text char

EXEC SQL TYPE text IS STRING(..);

The 'text' macro has never been expanded. This caveat of Pro*C/C++ is

well documented in the manual. It is mentioned here because in earlier

versions of Oracle releases, the 'text' word was defined using a C

typedef which would have allowed the above EXEC SQL TYPE statement to

work.

In the event that an Oracle bundled release changes the definition of

'text' from a typedef to a macro, any SQL directives such as the one

above would thus fail to precompile.

MISCELLANEOUS ISSUES

--------------------

Support for Object Navigation

-----------------------------

Another alternative for the application programmer is to use the Navigational

(ORI) routines within or in conjunction with a Pro*C/C++ program, after

connecting to the database(s) in Pro*C/C++. As described in Section 1 above,

an 8.0.4 OCI environment handle and the service context handle for a given

database connection may be obtained using the new library functions provided

by SQLLIB.

Multi-row Bulk (Array) Operations in Embedded SQL

-------------------------------------------------

Multi-row array operations for objects (ADTs) require that the host variable

arrays be *pointers* to the OTT-generated C structs, for both input and output.

Likewise, multi-row array operations on REF variables (of C type OCIRef) and

LOB locators (of C types OCIBlobLocator, OCIClobLocator) require that the host

arrays be pointers of the appropriate C type. For example, a valid

declaration of such arrays in a Pro*C/C++ program appears as:

OCIRef *ref_array[..];

OCIBlobLocator *blob_array[..];

OCIClobLocator *clob_array[..];

The PARSE command line option and its value

-------------------------------------------

The default value of the PARSE option is set to FULL so that Pro*C/C++ will

fully preprocess and parse the entire program. This is required especially

when using the Object features provided by Oracle 8.0.4.