Support error reporting APIs in ibm_db_dbi: conn_errormsg, conn_error, stmt_errormsg, stmt_error, get_sqlcode (ibmdb#1025)

* Support error reporting APIs in ibm_db_dbi: conn_errormsg, conn_error, stmt_errormsg, stmt_error, get_sqlcode
---------
Signed-off-by: Balram Choudhary <bchoudhary@rocketsoftware.com>

Author: bchoudhary6415

INSTALL.md

@@ -383,6 +383,12 @@ else:
 print('ODBC Test end')
 ```
 
+#### Troubleshooting
+
+**Important:** When working with `ibm_db` or `ibm_db_dbi` on z/OS environments such as USS and BPXBATCH, always use the provided APIs — `conn_errormsg()`, `conn_error()`, `stmt_errormsg()`, `stmt_error()`, and `get_sqlcode()` — to retrieve error messages, SQLSTATE and SQLCODE values for connection or statement failures.
+Avoid using direct `print()` statements or relying on raw exception output, as this may result in missing or unreadable error messages, or `UnicodeDecodeError` due to encoding limitations on these platforms.
+These APIs ensure consistent and reliable error handling across all supported environments.
+
 ## <a name="m1chip"></a> 3. ibm_db installation on MacOS M1/M2 Chip System (arm64 architecture)
 **Important:
 > ibm_db@3.2.5 onwards supports native installation on MacOS ARM64(M* Chip/Apple Silicon Chip) system using clidriver/dsdriver version 12.1.0.

ibm_db_dbi.py

@@ -492,6 +492,87 @@ def _get_exception(inst):
         return NotSupportedError(message)
     return DatabaseError(message)
 
+def conn_errormsg(connection=None):
+    """
+    Module-level wrapper for ibm_db.conn_errormsg().
+
+    When no connection handle is passed, returns the last global connection error message.
+    When a valid IBM_DBConnection handle is passed, returns the error for that connection.
+
+    Args:
+        connection: Optional IBM_DBConnection handle (default None).
+
+    Returns:
+        str: SQLCODE and error message describing the last connection error,
+             or empty string if no error.
+    """
+    LogMsg(INFO, "entry conn_errormsg()")
+    if connection is not None:
+        LogMsg(DEBUG, f"Getting connection error message for connection handle: {connection}")
+        err_msg = ibm_db.conn_errormsg(connection)
+    else:
+        LogMsg(DEBUG, "Getting global last connection error message (no handle passed)")
+        err_msg = ibm_db.conn_errormsg()
+    LogMsg(DEBUG, f"conn_errormsg result: {err_msg!r}")
+    LogMsg(INFO, "exit conn_errormsg()")
+    return err_msg
+
+def conn_error(connection=None):
+    """
+    Module-level wrapper for ibm_db.conn_error().
+
+    When no connection handle is passed, returns the last global SQLSTATE for a connection error.
+    When a valid IBM_DBConnection handle is passed, returns the SQLSTATE for that connection.
+
+    Args:
+        connection: Optional IBM_DBConnection handle (default None).
+
+    Returns:
+        str: SQLSTATE string representing the reason the last connection operation failed,
+             or an empty string if no error occurred.
+    """
+    LogMsg(INFO, "entry conn_error()")
+    if connection is not None:
+        LogMsg(DEBUG, f"Getting connection SQLSTATE for connection handle: {connection}")
+        sqlstate = ibm_db.conn_error(connection)
+    else:
+        LogMsg(DEBUG, "Getting global last connection SQLSTATE (no handle passed)")
+        sqlstate = ibm_db.conn_error()
+    LogMsg(DEBUG, f"conn_error result: {sqlstate!r}")
+    LogMsg(INFO, "exit conn_error()")
+    return sqlstate
+
+
+def get_sqlcode(handle=None):
+    """
+    Retrieve the SQLCODE of the last operation performed.
+
+    When no handle is passed, returns the SQLCODE for the last global operation.
+
+    When a valid IBM_DBConnection or IBM_DBStatement handle is passed, returns
+    the SQLCODE for the last operation using that resource.
+
+    Args:
+        handle (optional): IBM_DBConnection or IBM_DBStatement handle.
+
+    Returns:
+        str: SQLCODE string representing the last error code,
+             or empty string if no error occurred.
+    """
+    LogMsg(INFO, "entry get_sqlcode()")
+
+    if handle is not None:
+        LogMsg(DEBUG, f"Getting SQLCODE for handle: {handle}")
+        sqlcode = ibm_db.get_sqlcode(handle)
+    else:
+        LogMsg(DEBUG, "Getting global last SQLCODE (no handle passed)")
+        sqlcode = ibm_db.get_sqlcode()
+
+    LogMsg(DEBUG, f"get_sqlcode result: {sqlcode}")
+    LogMsg(INFO, "exit get_sqlcode()")
+
+    return sqlcode
+
 
 def _retrieve_current_schema(dsn):
     """This method retrieve the value of ODBC keyword CURRENTSCHEMA from DSN
@@ -1657,6 +1738,51 @@ def _get_last_identity_val(self):
 
     last_identity_val = property(_get_last_identity_val, None, None, "")
 
+    def stmt_errormsg(self):
+        """
+        Retrieve the SQLCODE and error message for the last operation performed
+        using this cursor's statement handle.
+
+        If `self.stmt_handler` is set (not None), returns the error specific to that statement.
+        Otherwise, returns the last global error message.
+
+        Returns:
+            str: SQLCODE and error message describing why the last operation failed,
+                 or an empty string if no error occurred.
+        """
+        LogMsg(INFO, "entry stmt_errormsg()")
+        if self.stmt_handler is not None:
+            LogMsg(DEBUG, f"Getting statement error message for stmt_handler: {self.stmt_handler}")
+            err_msg = ibm_db.stmt_errormsg(self.stmt_handler)
+        else:
+            LogMsg(DEBUG, "Getting global last statement error message (no stmt_handler set)")
+            err_msg = ibm_db.stmt_errormsg()
+        LogMsg(DEBUG, f"stmt_errormsg result: {err_msg!r}")
+        LogMsg(INFO, "exit stmt_errormsg()")
+        return err_msg
+
+    def stmt_error(self):
+        """
+        Retrieve the SQLSTATE code for the last operation performed using this cursor's statement handle.
+
+        If `self.stmt_handler` is set (not None), returns the SQLSTATE specific to that statement.
+        Otherwise, returns the last global SQLSTATE from ibm_db.stmt_error().
+
+        Returns:
+            str: SQLSTATE code representing the reason the last operation failed,
+                 or an empty string if there was no error.
+        """
+        LogMsg(INFO, "entry stmt_error()")
+        if self.stmt_handler is not None:
+            LogMsg(DEBUG, f"Getting statement SQLSTATE for stmt_handler: {self.stmt_handler}")
+            sqlstate = ibm_db.stmt_error(self.stmt_handler)
+        else:
+            LogMsg(DEBUG, "Getting global last statement SQLSTATE (no stmt_handler set)")
+            sqlstate = ibm_db.stmt_error()
+        LogMsg(DEBUG, f"stmt_error result: {sqlstate!r}")
+        LogMsg(INFO, "exit stmt_error()")
+        return sqlstate
+
     def execute(self, operation, parameters=None):
         """
         This method can be used to prepare and execute an SQL

ibm_db_tests/test_316_stmtErrormsg_stmtError_DBI.py

@@ -0,0 +1,47 @@
+#
+#  Licensed Materials - Property of IBM
+#
+#  (c) Copyright IBM Corp. 2025
+#
+
+from __future__ import print_function
+import sys
+import unittest
+import ibm_db
+import ibm_db_dbi
+import config
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_316_stmtErrormsg_stmtError_DBI(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expect(self.run_test_316)
+
+    def run_test_316(self):
+        conn = ibm_db_dbi.connect(config.database, config.user, config.password)
+        cursor = conn.cursor()
+
+        try:
+            cursor.execute("INVALID SQL")
+        except Exception:
+            print(cursor.stmt_errormsg())
+            print(cursor.stmt_error())
+
+        cursor.close()
+        conn.close()
+
+#__END__
+#__LUW_EXPECTED__
+#[IBM][CLI Driver][DB2/LINUXX8664] SQL0104N  An unexpected token "END-OF-STATEMENT" was found following "INVALID SQL".  Expected tokens may include:  "JOIN <joined_table>".  SQLSTATE=42601  SQLCODE=-104
+#42601
+#__ZOS_EXPECTED__
+#[IBM][CLI Driver][DB2/LINUXX8664] SQL0104N  An unexpected token "END-OF-STATEMENT" was found following "INVALID SQL".  Expected tokens may include:  "JOIN <joined_table>".  SQLSTATE=42601  SQLCODE=-104
+#42601
+#__SYSTEMI_EXPECTED__
+#[IBM][CLI Driver][AS] SQL0104N  An unexpected token "END-OF-STATEMENT" was found following "INVALID SQL".  Expected tokens may include:  "JOIN <joined_table>".  SQLSTATE=42601  SQLCODE=-104
+#42601
+#__IDS_EXPECTED__
+#[IBM][CLI Driver][IDS/LINUXX8664] SQL0104N  An unexpected token "END-OF-STATEMENT" was found following "INVALID SQL".  Expected tokens may include:  "JOIN <joined_table>".  SQLSTATE=42601  SQLCODE=-104
+#42601

ibm_db_tests/test_317_connErrormsg_connError_DBI.py

@@ -0,0 +1,43 @@
+#
+#  Licensed Materials - Property of IBM
+#
+#  (c) Copyright IBM Corp. 2025
+#
+
+from __future__ import print_function
+import sys
+import unittest
+import ibm_db
+import ibm_db_dbi
+import config
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_317_connErrormsg_connError_DBI(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expect(self.run_test_317)
+
+    def run_test_317(self):
+        try:
+            # Intentionally wrong credentials to trigger connection failure
+            conn = ibm_db_dbi.connect(config.database, "wrongUser", "wrongPassword")
+            print(conn)  # Should not get here
+        except Exception:
+            print(ibm_db_dbi.conn_errormsg())
+            print(ibm_db_dbi.conn_error())
+
+#__END__
+#__LUW_EXPECTED__
+#[IBM][CLI Driver] SQL30082N  Security processing failed with reason "24" ("USERNAME AND/OR PASSWORD INVALID").  SQLSTATE=08001  SQLCODE=-30082
+#08001
+#__ZOS_EXPECTED__
+#[IBM][CLI Driver] SQL30082N  Security processing failed with reason "24" ("USERNAME AND/OR PASSWORD INVALID").  SQLSTATE=08001  SQLCODE=-30082
+#08001
+#__SYSTEMI_EXPECTED__
+#[IBM][CLI Driver] SQL30082N  Security processing failed with reason "24" ("USERNAME AND/OR PASSWORD INVALID").  SQLSTATE=08001  SQLCODE=-30082
+#08001
+#__IDS_EXPECTED__
+#[IBM][CLI Driver] SQL30082N  Security processing failed with reason "24" ("USERNAME AND/OR PASSWORD INVALID").  SQLSTATE=08001  SQLCODE=-30082
+#08001

ibm_db_tests/test_318_get_sqlcode_DBI.py

@@ -0,0 +1,49 @@
+#
+#  Licensed Materials - Property of IBM
+#
+#  (c) Copyright IBM Corp. 2025
+#
+
+from __future__ import print_function
+import sys
+import unittest
+import ibm_db
+import ibm_db_dbi
+import config
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_318_get_sqlcode_DBI(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expect(self.run_test_318)
+
+    def run_test_318(self):
+        try:
+            # Intentionally wrong credentials to trigger connection failure
+            conn = ibm_db_dbi.connect(config.database, "wrongUser", "wrongPassword")
+            print(conn)  # Should not get here
+        except Exception:
+            print(ibm_db_dbi.get_sqlcode())
+
+        try:
+            conn1 = ibm_db_dbi.connect(config.database, config.user, config.password)
+            cursor = conn1.cursor()
+            cursor.execute("create table index_test(id int, data VARCHAR(50)")
+        except Exception:
+            print(ibm_db_dbi.get_sqlcode())
+
+#__END__
+#__LUW_EXPECTED__
+#SQLCODE=-30082
+#SQLCODE=-104
+#__ZOS_EXPECTED__
+#SQLCODE=-30082
+#SQLCODE=-104
+#__SYSTEMI_EXPECTED__
+#SQLCODE=-30082
+#SQLCODE=-104
+#__IDS_EXPECTED__
+#SQLCODE=-30082
+#SQLCODE=-104