FIX: cursor.execute() with reset_cursor=False raises Invalid cursor state (#521)

### Work Item / Issue Reference  
<!-- 
IMPORTANT: Please follow the PR template guidelines below.
For mssql-python maintainers: Insert your ADO Work Item ID below 
For external contributors: Insert Github Issue number below
Only one reference is required - either GitHub issue OR ADO Work Item.
-->

<!-- mssql-python maintainers: ADO Work Item -->
>
[AB#44009](https://sqlclientdrivers.visualstudio.com/c6d89619-62de-46a0-8b46-70b92a84d85e/_workitems/edit/44009)

<!-- External contributors: GitHub Issue -->
> GitHub Issue: #506 

-------------------------------------------------------------------
### Summary   
This pull request improves the handling of cursor state when executing
prepared statements with `reset_cursor=False`, ensuring that the
prepared plan is correctly reused and the cursor state is properly
managed between executions. It introduces a new `close_cursor` method at
the ODBC statement handle level, updates the Python bindings, and adds
comprehensive tests to verify the new behavior.

**Enhancements to cursor state management:**

- Added logic in `cursor.py` to call `hstmt.close_cursor()` (which
issues an ODBC `SQLFreeStmt(SQL_CLOSE)`) when `reset_cursor=False`,
allowing prepared statements to be reused safely without resetting the
entire cursor state. This resolves issues with invalid cursor state on
re-execution.

**ODBC handle and Python bindings updates:**

- Implemented the `close_cursor` method in the `SqlHandle` C++ class,
which closes only the cursor on the statement handle without freeing the
prepared statement.
- Exposed the new `close_cursor` method to Python via the
`ddbc_bindings` Pybind11 module, allowing it to be called from Python
code.

**Testing improvements:**

- Added multiple test cases in `test_004_cursor.py` to verify that
`reset_cursor=False` correctly reuses prepared plans, returns new
results, works across multiple iterations, handles queries without
parameters, and functions correctly when the previous result set was not
fully consumed.

Author: jahnvi480

mssql_python/cursor.py

@@ -1365,6 +1365,16 @@ def execute(  # pylint: disable=too-many-locals,too-many-branches,too-many-state
         if reset_cursor:
             logger.debug("execute: Resetting cursor state")
             self._reset_cursor()
+        else:
+            # Close just the ODBC cursor (not the statement handle) so the
+            # prepared plan can be reused.  SQLFreeStmt(SQL_CLOSE) releases
+            # the cursor associated with hstmt without destroying the
+            # prepared statement, which is the standard ODBC pattern for
+            # re-executing a prepared query.
+            if self.hstmt:
+                logger.debug("execute: Closing cursor for re-execution (reset_cursor=False)")
+                self.hstmt._close_cursor()
+                self._clear_rownumber()
 
         # Clear any previous messages
         self.messages = []

mssql_python/pybind/ddbc_bindings.cpp

@@ -1362,6 +1362,22 @@ void SqlHandle::free() {
     }
 }
 
+void SqlHandle::close_cursor() {
+    if (_type != SQL_HANDLE_STMT || !_handle) {
+        return;
+    }
+    if (_implicitly_freed) {
+        return;
+    }
+    if (!SQLFreeStmt_ptr) {
+        ThrowStdException("SQLFreeStmt function not loaded");
+    }
+    SQLRETURN ret = SQLFreeStmt_ptr(_handle, SQL_CLOSE);
+    if (ret != SQL_SUCCESS && ret != SQL_SUCCESS_WITH_INFO) {
+        ThrowStdException("SQLFreeStmt(SQL_CLOSE) failed");
+    }
+}
+
 SQLRETURN SQLGetTypeInfo_Wrapper(SqlHandlePtr StatementHandle, SQLSMALLINT DataType) {
     if (!SQLGetTypeInfo_ptr) {
         ThrowStdException("SQLGetTypeInfo function not loaded");
@@ -5740,7 +5756,8 @@ PYBIND11_MODULE(ddbc_bindings, m) {
         .def_readwrite("ddbcErrorMsg", &ErrorInfo::ddbcErrorMsg);
 
     py::class_<SqlHandle, SqlHandlePtr>(m, "SqlHandle")
-        .def("free", &SqlHandle::free, "Free the handle");
+        .def("free", &SqlHandle::free, "Free the handle")
+        .def("_close_cursor", &SqlHandle::close_cursor, "Internal: close the cursor without freeing the prepared statement");
 
     py::class_<ConnectionHandle>(m, "Connection")
         .def(py::init<const std::string&, bool, const py::dict&>(), py::arg("conn_str"),

mssql_python/pybind/ddbc_bindings.h

@@ -378,6 +378,7 @@ class SqlHandle {
     SQLHANDLE get() const;
     SQLSMALLINT type() const;
     void free();
+    void close_cursor();
 
     // Mark this handle as implicitly freed (freed by parent handle)
     // This prevents double-free attempts when the ODBC driver automatically

tests/test_004_cursor.py

@@ -16253,3 +16253,85 @@ def reader(reader_id):
     finally:
         stop_event.set()
         mssql_python.native_uuid = original
+
+
+def test_execute_reset_cursor_false_reuses_prepared_plan(db_connection):
+    """Test that reset_cursor=False reuses the prepared statement handle
+    and successfully re-executes after consuming the previous result set."""
+    cursor = db_connection.cursor()
+    try:
+        cursor.execute("SELECT 1 AS val WHERE 1 = ?", (1,))
+        row = cursor.fetchone()
+        assert row[0] == 1
+        _ = cursor.fetchall()  # consume remaining
+
+        # Re-execute with reset_cursor=False — this was raising
+        # ProgrammingError: Invalid cursor state before the fix.
+        cursor.execute("SELECT 1 AS val WHERE 1 = ?", (2,), reset_cursor=False)
+        row = cursor.fetchone()
+        assert row is None  # No match for WHERE 1 = 2
+    finally:
+        cursor.close()
+
+
+def test_execute_reset_cursor_false_returns_new_results(db_connection):
+    """Test that reset_cursor=False correctly returns results from the
+    second execution with different parameter values."""
+    cursor = db_connection.cursor()
+    try:
+        cursor.execute("SELECT ? AS val", (42,))
+        row = cursor.fetchone()
+        assert row[0] == 42
+        _ = cursor.fetchall()
+
+        cursor.execute("SELECT ? AS val", (99,), reset_cursor=False)
+        row = cursor.fetchone()
+        assert row[0] == 99
+    finally:
+        cursor.close()
+
+
+def test_execute_reset_cursor_false_multiple_iterations(db_connection):
+    """Test that reset_cursor=False works across several consecutive
+    re-executions on the same cursor."""
+    cursor = db_connection.cursor()
+    try:
+        for i in range(5):
+            kwargs = {"reset_cursor": False} if i > 0 else {}
+            cursor.execute("SELECT ? AS iter", (i,), **kwargs)
+            row = cursor.fetchone()
+            assert row is not None, f"Expected row with value {i}, got None"
+            assert row[0] == i, f"Expected {i}, got {row[0]}"
+            _ = cursor.fetchall()
+    finally:
+        cursor.close()
+
+
+def test_execute_reset_cursor_false_no_params(db_connection):
+    """Test that reset_cursor=False works for queries without parameters."""
+    cursor = db_connection.cursor()
+    try:
+        cursor.execute("SELECT 1 AS a")
+        _ = cursor.fetchall()
+
+        cursor.execute("SELECT 2 AS a", reset_cursor=False)
+        row = cursor.fetchone()
+        assert row[0] == 2
+    finally:
+        cursor.close()
+
+
+def test_execute_reset_cursor_false_after_fetchone_only(db_connection):
+    """Test reset_cursor=False when only fetchone() was called (result set
+    not fully consumed via fetchall)."""
+    cursor = db_connection.cursor()
+    try:
+        cursor.execute("SELECT ? AS val", (1,))
+        row = cursor.fetchone()
+        assert row[0] == 1
+        # Do NOT call fetchall — go straight to re-execute
+        cursor.execute("SELECT ? AS val", (2,), reset_cursor=False)
+        row = cursor.fetchone()
+        assert row[0] == 2
+    finally:
+        cursor.close()