ODPI-C Release notes
Version 3.1.1 (February 4, 2019)
- Improved code preventing a statement from binding itself, in order to avoid
a potential segfault under certain cirumstances.
- Always set
dpiConnCreateParams.outNewSession
to the appropriate
value when calling dpiPool_acquireConnection()
or
dpiConn_create()
.
- Worked around OCI bug when attempting to free objects that are PL/SQL
records, in order to avoid a potential segfault.
- Added samples demonstrating how to fetch CLOBs as strings and BLOBs as
bytes (preferred for smaller LOBs).
- Documentation improvements based on feedback
(issue 87,
issue 88,
issue 90,
issue 91,
issue 92).
Version 3.1 (January 21, 2019)
- Added support for getting and setting raw attributes of objects, as
requested (issue 72).
- Added function
dpiData_getIsNull()
for getting the null indicator
from a dpiData structure and function
dpiData_setNull()
for setting a value to null, as requested
(issue 82).
- Added support for fetching SYS.XMLTYPE objects as string data,
limited to the VARCHAR2 length (cx_Oracle issue 14).
- Added support for multi-property session tags and added attribute
dpiPoolCreateParams.plsqlFixupCallback
for identifying a PL/SQL
callback that will be executed when a requested tag doesn’t match the
tag associated with a pooled connection. Both of these features are only
available in Oracle Client 12.2 and higher.
- The attribute
dpiConnCreateParams.outNewSession
was added to
support determining if a session in a pool is completely new and has never
been acquired from the pool.
- Added support for performing external authentication with proxy for
standalone connections.
- Added error message when external authentication with proxy is attempted
without placing the user name in [] (proxy authentication is otherwise
silently ignored).
- Exempted additional error messages from forcing the statement to be dropped
from the cache (issue 76).
- Tightened up handling of numeric values when converted from a string
representation. The error message returned when the string cannot be
converted to an Oracle number was also improved.
- Completed enabling of pool pinging functionality for 12.2+ clients (see
attribute
dpiPoolCreateParams.pingInterval
for more information
on this feature).
- Ensured that the connection returned from the pool after a failed ping
(such as due to a killed session) is not itself marked as needing to be
dropped.
- Eliminated memory leak under certain circumstances when pooled connections
are released back to the pool.
- Eliminated memory leak when connections are dropped from the pool.
- Eliminated memory leak when calling
dpiConn_close()
after fetching
collections from the database.
- Adjusted order in which memory is freed when the last references to SODA
collections, documents, document cursors and collection cursors are
released, in order to prevent a segfault under certain circumstances.
- Improved error message when using an older version of the ODPI-C library.
- Added additional test cases.
- Improved documentation.
Version 3.0.0 (September 13, 2018)
- Added support for Oracle Client 18 libraries.
- Added support for SODA (as preview). See
SODA Database,
SODA Collection and
SODA Document for more information.
- Added support for call timeouts available in Oracle Client 18.1 and higher.
See functions
dpiConn_setCallTimeout()
and
dpiConn_getCallTimeout()
.
- Added support for setting a LOB attribute of an object with string/bytes
using the function
dpiObject_setAttributeValue()
.
- Added support for the packed decimal type used by object attributes with
historical types DECIMAL and NUMERIC
(cx_Oracle issue 212).
- On Windows, first attempt to load oci.dll from the same directory as the
module that contains ODPI-C.
- SQL Objects that are created or fetched from the database are now tracked
and marked unusable when a connection is closed. This was done in order to
avoid a segfault in some circumstances.
- Improved support for closing pools by ensuring that once a pool has closed,
further attempts to use connections acquired from that pool will fail with
error “DPI-1010: not connected”.
- Re-enabled pool pinging functionality for Oracle Client 12.2 and higher
to handle classes of connection errors such as resource profile limits.
- Improved error messages when the Oracle Client or Oracle Database need to
be at a minimum version in order to support a particular feature.
- Use plain integers instead of enumerations in order to simplify code and
reduce the requirement for casts. Typedefs have been included so that code
does not need to be changed.
- Eliminated potential buffer overrun
(issue 69).
- In the Makefile for non-Windows platforms, the version information for
ODPI-C is acquired directly from include/dpi.h as suggested
(issue 66).
- Removed function dpiConn_newSubscription(). Use function
dpiConn_subscribe()
instead.
- Removed function dpiLob_flushBuffer(). This function never worked anyway.
- Removed function dpiSubscr_close(). Use function
dpiConn_unsubscribe()
instead.
- Removed function dpiVar_getData(). Use function
dpiVar_getReturnedData()
instead.
- Added additional test cases.
- Improved documentation.
Version 2.4.2 (July 9, 2018)
- Avoid buffer overrun due to improper calculation of length byte when
converting some negative 39 digit numbers from string to the internal
Oracle number format
(issue 67).
Version 2.4.1 (July 2, 2018)
- Use the install_name_tool on macOS to adjust the library name, as suggested
(issue 65).
- Even when dequeue fails OCI still provides a message id so make sure it is
deallocated to avoid a memory leak.
- Ensure that the row count for queries is reset to zero when the statement
is executed (cx_Oracle issue 193).
- If the statement should be deleted from the statement cache, first check to
see that there is a statement cache currently being used; otherwise, the
error “ORA-24300: bad value for mode” will be raised under certain
conditions.
Version 2.3.2 (May 7, 2018)
- Ensure that a call to unregister a subscription only occurs if the
subscription is still registered.
- Ensure that before a statement is executed that any dynamic buffers created
for DML returning statments are reset since the out bind callback is not
called if no rows are returned!
- Silenced compilation warning in test suite.
- Added test cases for DML returning statements.
Version 2.3.1 (April 25, 2018)
- Fixed determination of the number of rows returned in a DML Returning
statement when the same statement is executed multiple times in succession
with less rows being returned in each succeeding execution.
- Stopped attempting to unregister a CQN subscription before it was
completely registered. This prevents errors encountered during registration
from being masked by an error stating that the subscription has not been
registered!
- Fixed support for true heterogeneous session pools that use different
user/password combinations for each session acquired from the pool.
- Added error message indicating that modes DPI_MODE_EXEC_BATCH_ERRORS and
DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS are only supported with insert, update,
delete and merge statements.
- Corrected comment
(issue 61).
- Renamed internal method dpiStmt__preFetch() to dpiStmt__beforeFetch() in
order to avoid confusion with OCI prefetch.
Version 2.3 (April 2, 2018)
- Corrected support for getting the OUT values of bind variables bound to a
DML Returning statement when calling the function
dpiStmt_executeMany()
. Since multiple rows can be returned for each
iteration, a new function dpiVar_getReturnedData()
has been added
and the original function dpiVar_getData()
has been deprecated and
will be removed in version 3.
- Corrected binding of LONG data (values exceeding 32KB) when using the
function
dpiStmt_executeMany()
.
- Added code to verify that the CQN subscription is open before permitting it
to be used. Error “DPI-1060: subscription was already closed” will now be
raised if an attempt is made to use a subscription that was closed earlier.
- Added error “DPI-1061: edition is not supported when a new password is
specified” to clarify the fact that specifying an edition and a new
password at the same time is not supported. Previously the edition value
was simply ignored.
- Query metadata is no longer fetched if executing a statement with mode
DPI_MODE_EXEC_PARSE_ONLY.
- Added additional statement types (DPI_STMT_TYPE_EXPLAIN_PLAN,
DPI_STMT_TYPE_ROLLBACK and DPI_STMT_TYPE_COMMIT) as well as one that covers
statement types not currently identified (DPI_STMT_TYPE_UNKNOWN).
- Improved error message when older OCI client libraries are being used that
don’t have the method OCIClientVersion().
- Corrected the handling of ANSI types REAL and DOUBLE PRECISION as
implemented by Oracle. These types are just subtypes of NUMBER and are
different from BINARY_FLOAT and BINARY_DOUBLE (cx_Oracle issue 163).
- Added check that the return value from OCI functions matches the expected
value of OCI_ERROR, and if not, raises an error including the value that
was actually returned.
- Added additional test cases.
- Removed unused error messages.
Version 2.2.1 (March 5, 2018)
- Maintain a reference to the “parent” object and use the actual object
instance instead of a copy, so that “child” objects can be manipulated
in-place instead of having to be created externally and then set
(attributes) or appended (collections).
- Correct handling of boundary numbers 1e126 and -1e126.
- Eliminate memory leak when calling
dpiConn_deqObject()
and
dpiConn_enqObject()
.
- Eliminate memory leak when setting NCHAR and NVARCHAR attributes of
objects.
- Eliminate memory leak when fetching collection objects from the database.
- Prevent internal re-execution of statement from duplicating itself in the
list of open statements maintained on the connection.
- Improved documentation.
Version 2.2 (February 14, 2018)
- Keep track of open statements and LOBs and automatically close them when
the connection is closed; this eliminates the need for users of the driver
to do so and removes the error “DPI-1054: connection cannot be closed when
open statements or LOBs exist”.
- Ignore failures that occur during the implicit rollback performed when a
connection is closed, but if an error does occur, ensure that the
connection is dropped from the pool (if it was acquired from a pool); such
failures are generally due to an inability to communicate with the server
(such as when your session has been killed).
- Avoid a round trip to the database when a connection is released back to
the pool by preventing a rollback from being called when there is no
transaction in progress.
- Improve error message when the use of bind variables is attempted with DDL
statements, which is not supported.
- Since rowid is returned as a handle, the size in bytes and characters was
simply being returned as the size of a pointer; set these values to 0
instead as is done with other handles that are returned.
- Ensure that the LOB locator returned from the object attribute or element
is not used directly as freeing it will result in unexpected behavior when
the object containing it is itself freed.
- Make a copy of any objects that are acquired from other objects (either as
attributes or elements of collections) in order to prevent possible use of
the object acquired in such a fashion after the object it came from has
been freed.
- Protect global variables on destruction as well since dpiGlobal__finalize()
may not be the last method that is called if other methods are registered
with atexit().
- Use cast to avoid assertions with isspace() when using debug libraries on
Windows (issue 52).
- Added file embed/dpi.c to simplify inclusion of ODPI-C in projects.
- Minor changes to satisfy pickier compilers and static analysis tools.
- Added additional test cases.
- Improved documentation.
Version 2.1 (December 12, 2017)
- Connections
- Support was added for accessing sharded databases via sharding keys (new
in Oracle 12.2). NOTE: the underlying OCI library has a bug when using
standalone connections. There is a small memory leak proportional to the
number of connections created/dropped. There is no memory leak when using
session pools, which is recommended.
- Added options for authentication with SYSBACKUP, SYSDG, SYSKM and SYSRAC,
as requested (cx_Oracle issue 101).
- Attempts to release statements or free LOBs after the connection has been
closed (by, for example, killing the session) are now prevented.
- An error message was added when specifying an edition and a connection
class since this combination is not supported.
- Attempts to close the session for connections created with an external
handle are now prevented.
- Attempting to ping a database earlier than 10g results in ORA-1010:
invalid OCI operation, but that implies a response from the database and
therefore a successful ping, so treat it that way!
(see https://github.com/rana/ora/issues/224 for more information).
- Objects
- Support was added for converting numeric values in an object type
attribute to integer and text, as requested (issue 35).
- Methods
dpiDeqOptions_setMsgId()
and
dpiMsgProps_setOriginalMsgId()
now set their values correctly.
- The overflow check when using double values as input to float attributes
of objects or elements of collections was removed as it didn’t work
anyway and is a well-known issue that cannot be prevented without
removing desired functionality. The developer should ensure that the
source value falls within the limits of floats, understand the consequent
precision loss or use a different data type.
- Variables
- Support was added for setting a LOB variable using
dpiVar_setFromBytes()
.
- Added support for the case when the time zone minute offset is negative,
as requested (issue 38).
- Variables of type DPI_NATIVE_TYPE_BYTES are restricted to 2 bytes less
than 1 GB (1,073,741,822 bytes), since OCI cannot handle more than that
currently.
- Miscellaneous
- Support was added for identifying the id of the transaction which spawned
a CQN subscription message, as requested
(issue 32).
- Corrected use of subscription port number (cx_Oracle issue 115).
- Added support for getting information about MERGE statements, as
requested (issue 40).
- Problems reported with the usage of FormatMessage() on Windows was
addressed (issue 47).
- On Windows, if oci.dll cannot be loaded because it is the wrong
architecture (32-bit vs 64-bit), attempt to find the offending DLL and
include the full path of the DLL in the message, as suggested
(issue 49).
- Debugging
- Support was added to the debugging infrastructure to print the thread id
and the date/time of messages. Support for an environment variable
DPI_DEBUG_PREFIX was also added. See ODPI-C Debugging.
- Support was added for debugging both entry and exit points of ODPI-C
public functions and for memory allocation/deallocation.
- Infrastructure
- Dependent libraries were moved to the main Makefile so that applications
do not have to do that, as suggested (issue 33).
- Added Makefile.win32 for the use of nmake on Windows and reworked
existing Makefiles to support only platforms other than Windows.
- Ensure that ODPI-C extended initialization code takes place before any
other ODPI-C code can take place, and that it takes place in only one
thread. Code was also added to cleanup the global OCI environment on
process exit.
- The OCI wrapers for using mutexes were eliminated, which improves
performance.
- Force OCI prefetch to always use the value 2; the OCI default is 1 but
setting the ODPI-C default to 2 ensures that single row fetches don’t
require an extra round trip to determine if there are more rows to fetch;
this change also reduces the potential memory consumption when
fetchArraySize was set to a large value and also avoids performance
issues discovered with larger values of prefetch.
- Unused parameters for internal functions were removed where possible and
__attribute((unused))
added where not possible, as requested
(issue 39).
- The use of OCIThreadKeyInit() in any code other than the global
initialization code was removed in order to avoid bugs in the OCI
library.
- Compiler warnings and Parfait warnings were eliminated.
- Added additional test cases.
- Documentation improvements.
- Deprecations
- The function dpiLob_flushBuffer() is deprecated and will be removed in
version 3. It previously always returned an error anyway because of the
inability to enable LOB buffering and now always returns the error
“DPI-1013: not supported”.
Version 2.0.3 (November 6, 2017)
- Prevent use of unitialized data in certain cases (cx_Oracle issue 77).
- Attempting to ping a database earlier than 10g results in error “ORA-1010:
invalid OCI operation”, but that implies a response from the database and
therefore a successful ping, so treat it that way!
- Some values represented as double do not convert perfectly to float; use
FLT_EPSILON to check the difference between the two after conversion,
rather than expect the values to convert perfectly.
- Prevent use of NaN with Oracle numbers since it produces corrupt data
(cx_Oracle issue 91).
- Verify that Oracle objects bound to cursors, fetched from cursors, set in
object attributes or appended to collection objects are of the correct
type.
- Correct handling of NVARCHAR2 when used as attributes of Oracle objects or
elements of collections
(issue 45).
Version 2.0.2 (August 30, 2017)
- Don’t prevent connection from being explicitly closed when a fatal error
has taken place (cx_Oracle issue 67).
- Correct handling of objects when dynamic binding is performed.
- Process deregistration events without an error.
- Eliminate memory leak when calling dpiObjectType_createObject().
Version 2.0.1 (August 18, 2017)
- Ensure that any allocated statement increments the open child count
(issue 27).
- Correct parameter subscrId to dpiConn_newSubscription() as
noted. There is no OCI
documentation for this attribute and should never have been exposed. The
parameter is therefore deprecated and will be removed in version 3. The
value NULL can now also be passed to this parameter.
- Add script for running valgrind and correct issues found in test suite
reported by valgrind
(issue 29).
- Use posix_spawn() instead of system() in the test suite, as requested
(issue 30).
- Add support for DML Returning statements that require dynamically allocated
variable data (such as CLOBs being returned as strings).
Version 2.0.0 (August 14, 2017)
- Added new structure dpiDataTypeInfo and modified
structures dpiQueryInfo,
dpiObjectAttrInfo and
dpiObjectTypeInfo in order to add support for
fractional seconds precision on timestamps and interval day to second
values (issue 22) and to
support additional metadata on object types and attributes
(issue 23).
- Prevent closing the connection when there are any open statements or LOBs
and add new error “DPI-1054: connection cannot be closed when open
statements or LOBs exist” when this situation is detected; this is needed
to prevent crashes under certain conditions when statements or LOBs are
being acted upon while at the same time (in another thread) a connection is
being closed; it also prevents leaks of statements and LOBs when a
connection is returned to a session pool.
- Added support for binding by value for rowids in
dpiStmt_bindValueByPos()
and dpiStmt_bindValueByName()
.
- On platforms other than Windows, if the regular method for loading the
Oracle Client libraries fails, try using $ORACLE_HOME/lib/libclntsh.so
(issue 20).
- Use the environment variable DPI_DEBUG_LEVEL at runtime, not compile time,
to add in debugging.
- Added support for DPI_DEBUG_LEVEL_ERRORS (reports errors and has the value
8) and DPI_DEBUG_LEVEL_SQL (reports prepared SQL statement text and has the
value 16) in order to further improve the ability to debug issues.
- Ensure that any prefetch activities are performed prior to performing the
fetch in
dpiStmt_scroll()
.
- Provide means of disabling thread cleanup for situations where threads are
created at startup and never terminated (such as takes place with Node.js).
- Add script sql/TestEnv.sql and read environment variables during test
execution in order to simplify the running of tests.
- Add script sql/SampleEnv.sql and read environment variables during sample
execution in order to simplify the running of samples.
- Adjust Makefile for tests and samples
(issue 24).
- Added additional test cases.
- Documentation improvements.
Version 2.0.0-rc.2 (July 20, 2017)
- Improved error messages when initial OCI environment cannot be created.
- On Windows, convert system message to Unicode first, then to UTF-8;
otherwise, the error message returned could be in a mix of encodings.
- Added support for converting from text to number in object attributes and
collection element values.
- Added checks on all pointers to ensure they are not NULL.
- Added checks on all pointer/length combinations to ensure that they are not
NULL and non-zero at the same time.
- Ensure that the thread specific errors are freed properly.
- Corrected handling of connections using DRCP.
- Corrected issue where error getting a pooled connection was masked by
error “DPI-1002: invalid OCI handle”.
- PL/SQL boolean values are not supported until Oracle Client 12.1 so raise
an unsupported error if an attempt is made to use them in Oracle Client
11.2.
- Allow the parameter numQueryColumns to be null in
dpiStmt_execute()
as a convenience to those who do not require that information.
- Added url fragment and whether a 32-bit or 64-bit library is expected to
error “DPI-1047: Oracle Client library cannot be loaded” in order to
improve the help provided.
- Added prefix “ODPI: ” to start of all debug messages to aid in
differentiating between them and other messages in log files.
- Added additional test cases.
- Documentation improvements.
Version 2.0.0-rc.1 (June 16, 2017)
- OCI requires that both
encoding
and nencoding
have values or that both
encoding and encoding do not have values. The missing value is set to its
default value if one of the values is set and the other is not
(issue 36).
- Add optimization when client and server character sets are identical; in
that case the size in bytes reported by the server is sufficient to hold
the data that will be transferred from the server and there is no need to
expand the buffer for character strings.
- Corrected handling of BFILE LOBs.
- Eliminated errors and warnings when using AIX compiler.
- Documentation improvements.
Version 2.0.0-beta.4 (May 24, 2017)
- Added support for getting/setting attributes of objects or element values
in collections that contain LOBs, BINARY_FLOAT values, BINARY_DOUBLE values
and NCHAR and NVARCHAR2 values. The error message for any types that are
not supported has been improved as well.
- Enabled temporary LOB caching in order to avoid disk I/O as
suggested.
- Changed default native type to DPI_ORACLE_TYPE_INT64 if the column metadata
indicates that the values are able to fit inside a 64-bit integer.
- Added function
dpiStmt_defineValue()
, which gives the application
the opportunity to specify the data type to use for fetching without having
to create a variable.
- Added constant DPI_DEBUG_LEVEL as a set of bit flags which result in
messages being printed to stderr. The following levels are defined:
- 0x0001 - reports errors during free operations
- 0x0002 - reports on reference count changes
- 0x0004 - reports on public function calls
- An empty string is just as acceptable as NULL when enabling external
authentication in
dpiPool_create()
.
- Avoid changing the OCI actual length values for fixed length types in order
to prevent error “ORA-01458: invalid length inside variable character
string”.
- Ensured that the length set in the dpiBytes structure by the caller is
passed through to the actual length buffer used by OCI.
- Added missing documentation for function
dpiVar_setFromBytes()
.
- Handle edge case when an odd number of zeroes trail the decimal point in a
value that is effectively zero (cx_Oracle issue 22).
- Eliminated resource leak when a standalone connection or pool is freed.
- Prevent attempts from binding the cursor being executed to itself.
- Corrected determination of unique bind variable names. The function
dpiStmt_getBindCount()
returns a count of unique bind variable
names for PL/SQL statements only. For SQL statements, this count is the
total number of bind variables, including duplicates. The function
dpiStmt_getBindNames()
has been adjusted to return the actual
number of unique bind variable names (parameter numBindNames is now a
pointer instead of a scalar value).
- Added additional test cases.
- Added check for Cygwin, as suggested.
Version 2.0.0-beta.2 (March 28, 2017)
- Use dynamic loading at runtime to load the OCI library and eliminate the
need for the OCI header files to be present when building ODPI-C.
- Improve sample Makefile as requested in issue 1.
- Correct support for handling unsigned integers that are larger than the
maximum size that can be represented by a signed integer. This corrects
issue 3.
- Remove type DPI_ORACLE_TYPE_LONG_NVARCHAR which is not needed as noted in
issue 5.
- Increase size of string which can be generated from an OCI number. This
corrects issue 6.
- Ensure that zeroing the check integer on ODPI-C handles is not optimised
away by the compiler.
- Silence compiler warnings from the Microsoft C++ compiler.
- Restore support for simple reference count tracing by the use of
DPI_TRACE_REFS.
- Add additional error (ORA-56600: an illegal OCI function call was issued)
to the list of errors that cause the session to be dropped from the session
pool.
- Changed LOB sample to include code to populate both CLOBs and BLOBs in
addition to fetching them.
Version 2.0.0-beta.1 (January 30, 2017)
- Initial release supporting the following features:
- 11.2, 12.1 and 12.2 Oracle Client support
- 9.2 and higher Oracle Database support (depending on Oracle Client
version)
- SQL and PL/SQL execution
- Character datatypes (CHAR, VARCHAR2, NCHAR, NVARCHAR2, CLOB, NCLOB, LONG)
- Numeric datatypes (NUMBER, BINARY_FLOAT, BINARY_DOUBLE)
- Dates, Timestamps, Intervals
- Binary types (BLOB, BFILE, RAW, LONG RAW)
- PL/SQL datatypes (PLS_INTEGER, BOOLEAN, Collections, Records)
- JSON
- User Defined Types
- REF CURSOR, Nested cursors, Implicit Result Sets
- Array fetch
- Array bind/execute
- Session pools (homogeneous and non-homogeneous with proxy authentication)
- Standalone connections
- Database Resident Connection Pooling (DRCP)
- External authentication
- Statement caching (tagging)
- End-to-end tracing, mid-tier authentication and auditing (action, module,
client identifier, client info, database operation)
- Edition Based Redefinition
- Scrollable cursors
- DML RETURNING
- Privileged connection support (SYSDBA, SYSOPER, SYSASM, PRELIM_AUTH)
- Database Startup/Shutdown
- Session Tagging
- Proxy authentication
- Batch Errors
- Array DML Row Counts
- Query Result Caching
- Application Continuity (with some limitations)
- Query Metadata
- Password Change
- Two Phase Commit
- OCI Client Version and Server Version
- Connection Validation (when acquired from session pool or DRCP)
- Continuous Query Notification
- Advanced Queuing
- Easily extensible (via direct OCI calls)