Added support for CLOBs that were originally created in Oracle Database 9i and

tidied up documentation on LOB locator flags as well as encoding names (now
using official names instead of aliases).

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -24,6 +24,7 @@ Thin Mode Changes
     (`issue 542 <https://github.com/oracle/python-oracledb/issues/542>`__).
 #)  Fixed bug writing boolean values to PL/SQL stored procedures and functions
     (`issue 568 <https://github.com/oracle/python-oracledb/issues/568>`__).
+#)  Added support for CLOBs that were originally created in Oracle Database 9i.
 
 
 Thick Mode Changes

src/oracledb/base_impl.pxd

@@ -217,6 +217,7 @@ cdef str ARRAY_TYPE_CODE_UINT32
 
 cdef const char* ENCODING_UTF8
 cdef const char* ENCODING_UTF16
+cdef const char* ENCODING_UTF16LE
 
 cdef class ApiType:
     cdef:

src/oracledb/base_impl.pyx

@@ -138,8 +138,9 @@ cdef const char* DRIVER_VERSION
 cdef const char* DRIVER_INSTALLATION_URL = \
         "https://python-oracledb.readthedocs.io/en/" \
         "latest/user_guide/initialization.html"
-cdef const char* ENCODING_UTF8 = "UTF-8"
-cdef const char* ENCODING_UTF16 = "UTF-16BE"
+cdef const char* ENCODING_UTF8 = "UTF_8"
+cdef const char* ENCODING_UTF16 = "UTF_16_BE"
+cdef const char* ENCODING_UTF16LE = "UTF_16_LE"
 
 # variables needed for dates when using pyarrow
 cdef cydatetime.datetime EPOCH_DATE = datetime.datetime(1970, 1, 1)

src/oracledb/impl/thin/constants.pxi

@@ -305,10 +305,14 @@ cdef enum:
 cdef enum:
     TNS_LOB_LOC_FLAGS_INIT = 0x08
 
+# LOB locator flags (byte 3)
+cdef enum:
+    TNS_LOB_LOC_FLAGS_VAR_LENGTH_CHARSET = 0x80
+
 # LOB locator flags (byte 4)
 cdef enum:
     TNS_LOB_LOC_FLAGS_TEMP = 0x01
-    TNS_LOB_LOC_FLAGS_VAR_LENGTH_CHARSET = 0x80
+    TNS_LOB_LOC_FLAGS_LITTLE_ENDIAN = 0x40
 
 # other LOB constants
 cdef enum:

src/oracledb/impl/thin/lob.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2020, 2025, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2026, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -198,11 +198,19 @@ cdef class BaseThinLobImpl(BaseLobImpl):
 
     cdef const char* _get_encoding(self):
         """
-        Return the encoding used by the LOB.
+        Return the encoding used by the LOB. NCLOB always uses UTF-16. CLOB
+        uses UTF-16 if the "variable length character set" flag is set, but
+        uses UTF-16LE if the "little endian" flag is set (this flag is only for
+        those CLOBs that were originally created in Oracle Database 9i). In all
+        other cases, the encoding UTF-8 is used.
         """
-        if self.dbtype._csfrm == CS_FORM_NCHAR \
-                or self._locator[TNS_LOB_LOC_OFFSET_FLAG_3] & \
+        if self.dbtype._csfrm == CS_FORM_NCHAR:
+            return ENCODING_UTF16
+        elif self._locator[TNS_LOB_LOC_OFFSET_FLAG_3] & \
                 TNS_LOB_LOC_FLAGS_VAR_LENGTH_CHARSET:
+            if self._locator[TNS_LOB_LOC_OFFSET_FLAG_4] & \
+                    TNS_LOB_LOC_FLAGS_LITTLE_ENDIAN:
+                return ENCODING_UTF16LE
             return ENCODING_UTF16
         return ENCODING_UTF8
 

src/oracledb/thin_impl.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2020, 2025, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2026, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -125,6 +125,7 @@ from .base_impl cimport (
     DRIVER_VERSION,
     ENCODING_UTF8,
     ENCODING_UTF16,
+    ENCODING_UTF16LE,
     GrowableBuffer,
     PY_TYPE_NUM_FLOAT,
     PY_TYPE_NUM_INT,