ODPI-C Release notes

Version 2.1 (December 12, 2017)

  1. 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).
  2. 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.
  3. 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.
  4. Miscellaneous
    • Support was added for identifying the id of the transaction which spawned a 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).
  5. 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.
  6. 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.
  7. 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)

  1. Prevent use of unitialized data in certain cases (cx_Oracle issue 77).
  2. 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!
  3. 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.
  4. Prevent use of NaN with Oracle numbers since it produces corrupt data (cx_Oracle issue 91).
  5. Verify that Oracle objects bound to cursors, fetched from cursors, set in object attributes or appended to collection objects are of the correct type.
  6. Correct handling of NVARCHAR2 when used as attributes of Oracle objects or elements of collections (issue 45).

Version 2.0.2 (August 30, 2017)

  1. Don’t prevent connection from being explicitly closed when a fatal error has taken place (cx_Oracle issue 67).
  2. Correct handling of objects when dynamic binding is performed.
  3. Process deregistration events without an error.
  4. Eliminate memory leak when calling dpiObjectType_createObject().

Version 2.0.1 (August 18, 2017)

  1. Ensure that any allocated statement increments the open child count (issue 27).
  2. 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 2.1. The value NULL can now also be passed to this parameter.
  3. Add script for running valgrind and correct issues found in test suite reported by valgrind (issue 29).
  4. Use posix_spawn() instead of system() in the test suite, as requested (issue 30).
  5. 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)

  1. 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).
  2. 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.
  3. Added support for binding by value for rowids in dpiStmt_bindValueByPos() and dpiStmt_bindValueByName().
  4. 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).
  5. Use the environment variable DPI_DEBUG_LEVEL at runtime, not compile time, to add in debugging.
  6. 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.
  7. Ensure that any prefetch activities are performed prior to performing the fetch in dpiStmt_scroll().
  8. Provide means of disabling thread cleanup for situations where threads are created at startup and never terminated (such as takes place with Node.js).
  9. Add script sql/TestEnv.sql and read environment variables during test execution in order to simplify the running of tests.
  10. Add script sql/SampleEnv.sql and read environment variables during sample execution in order to simplify the running of samples.
  11. Adjust Makefile for tests and samples (issue 24).
  12. Added additional test cases.
  13. Documentation improvements.

Version 2.0.0-rc.2 (July 20, 2017)

  1. Improved error messages when initial OCI environment cannot be created.
  2. On Windows, convert system message to Unicode first, then to UTF-8; otherwise, the error message returned could be in a mix of encodings.
  3. Added support for converting from text to number in object attributes and collection element values.
  4. Added checks on all pointers to ensure they are not NULL.
  5. Added checks on all pointer/length combinations to ensure that they are not NULL and non-zero at the same time.
  6. Ensure that the thread specific errors are freed properly.
  7. Corrected handling of connections using DRCP.
  8. Corrected issue where error getting a pooled connection was masked by error “DPI-1002: invalid OCI handle”.
  9. 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.
  10. Allow the parameter numQueryColumns to be null in dpiStmt_execute() as a convenience to those who do not require that information.
  11. 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.
  12. Added prefix “ODPI: ” to start of all debug messages to aid in differentiating between them and other messages in log files.
  13. Added additional test cases.
  14. Documentation improvements.

Version 2.0.0-rc.1 (June 16, 2017)

  1. 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).
  2. 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.
  3. Corrected handling of BFILE LOBs.
  4. Eliminated errors and warnings when using AIX compiler.
  5. Documentation improvements.

Version 2.0.0-beta.4 (May 24, 2017)

  1. 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.
  2. Enabled temporary LOB caching in order to avoid disk I/O as suggested.
  3. 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.
  4. 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.
  5. 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
  6. An empty string is just as acceptable as NULL when enabling external authentication in dpiPool_create().
  7. Avoid changing the OCI actual length values for fixed length types in order to prevent error “ORA-01458: invalid length inside variable character string”.
  8. Ensured that the length set in the dpiBytes structure by the caller is passed through to the actual length buffer used by OCI.
  9. Added missing documentation for function dpiVar_setFromBytes().
  10. Handle edge case when an odd number of zeroes trail the decimal point in a value that is effectively zero (cx_Oracle issue 22).
  11. Eliminated resource leak when a standalone connection or pool is freed.
  12. Prevent attempts from binding the cursor being executed to itself.
  13. 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).
  14. Added additional test cases.
  15. Added check for Cygwin, as suggested.

Version 2.0.0-beta.3 (April 18, 2017)

  1. Add initial set of functional test cases.
  2. Add support for smallint and float data types in Oracle objects, as requested.
  3. Ensure that the actual array size is set to the number of rows returned in a DML returning statement.
  4. Remove unneeded function dpiVar_resize().
  5. Improve error message when specifying an invalid array position in a variable.
  6. Add structure dpiVersionInfo to pass version information, rather than separate parameters. This affects functions dpiContext_getClientVersion() and dpiConn_getServerVersion().
  7. Rename functions that use an index to identify elements in a collection to include “ByIndex” in the name. This is clearer and also allows for functions that may be added in the future that will identify elements by other means. This affects functions dpiObject_deleteElementByIndex(), dpiObject_getElementExistsByIndex(), dpiObject_getElementValueByIndex(), and dpiObject_setElementValueByIndex().
  8. The OCI function OCITypeByFullName() is supported on a 12.1 Oracle Client but will give the error “OCI-22351: This API is not supported by the ORACLE server” when used against an 11.2 Oracle Database. The function dpiConn_getObjectType() now checks the server version and calls the correct routine as needed.
  9. Add parameter “exists” to functions dpiObject_getFirstIndex() and dpiObject_getLastIndex() which allow a calling program to avoid error “OCI-22166: collection is empty”.

Version 2.0.0-beta.2 (March 28, 2017)

  1. 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.
  2. Improve sample Makefile as requested in issue 1.
  3. 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.
  4. Remove type DPI_ORACLE_TYPE_LONG_NVARCHAR which is not needed as noted in issue 5.
  5. Increase size of string which can be generated from an OCI number. This corrects issue 6.
  6. Ensure that zeroing the check integer on ODPI-C handles is not optimised away by the compiler.
  7. Silence compiler warnings from the Microsoft C++ compiler.
  8. Restore support for simple reference count tracing by the use of DPI_TRACE_REFS.
  9. 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.
  10. 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)

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