FIx: Add opt-in batch error continuation for sqlsrv and PDO next-result APIs (#1600)

* Fix #1599: Remove SQLCancel from core_sqlsrv_next_result catch block

When SQLMoreResults returns SQL_ERROR for a mid-batch statement failure
(e.g. divide-by-zero with XACT_ABORT OFF), the statement handle remains
valid.  The old code called SQLCancel() in the catch block, which aborted
the entire remaining batch.

This change:
1. Removes SQLCancel from the catch block so the handle stays alive.
2. Adds a throw_on_errors parameter (default true) to
   core_sqlsrv_next_result to scope the non-throwing behaviour:
   - throw_on_errors=true  (flush loops, closeCursor, param binding):
     uses the throwing core::SQLMoreResults wrapper — SQL_ERROR exits
     the loop via exception.  Same behaviour as before.
   - throw_on_errors=false (sqlsrv_next_result / PDO::nextRowset):
     calls SQLMoreResults directly, reports the error through the
     normal error handler, clears any pending PDO exception, and
     falls through to new_result_set().  The batch remains navigable.
3. Tests both extensions (ERRMODE_WARNING and ERRMODE_EXCEPTION for PDO)
   and verifies re-execute after a batch error (flush loop).

Fixes #1599

* Implement opt-in batch error continuation with legacy default

Add optional batch error continuation controls for both sqlsrv and PDO
next-result APIs, preserving legacy fail-on-error behavior by default
while allowing users to opt-in to continue-after-error semantics.

Changes:
- Add batch_error_continue boolean flag to shared connection struct
- Initialize flag to false to preserve backward-compatible behavior
- Expose BatchErrorContinue option for sqlsrv_connect()
- Expose SQLSRV_ATTR_BATCH_ERROR_CONTINUE attribute for PDO
- Gate both sqlsrv_next_result() and PDOStatement::nextRowset() on flag
- Updated tests to validate both default and opt-in behaviors

Design:
- Default (batch_error_continue=false): sqlsrv_next_result/nextRowset
  return false on mid-batch SQL errors, matching pre-fix semantics
- Opt-in (batch_error_continue=true): continue past mid-batch errors
  while reporting them via sqlsrv_errors()/errorInfo()

Impact:
- Existing applications unaffected; no behavior changes without opt-in
- Users must explicitly set the flag to enable new behavior
- Full backward compatibility maintained

* Harden opt-in batch error continuation without breaking defaults

- Split non-throwing next-result behavior into explicit modes
  (silent internal drain vs opt-in user-facing diagnostics)
- Preserve default re-execute flush semantics (no surfaced diagnostics)
- Gate sqlsrv_next_result/PDO nextRowset reporting strictly on opt-in
- Guard zend_clear_exception behind pending-exception check
- Reduce test flakiness by asserting diagnostic presence instead of fixed SQLSTATE
- Add coverage for default silent re-execute and PDO constructor opt-in path
- Clarify connection-scope behavior in code and changelog (issue #1599)

* Fix batch error tests: use RAISERROR instead of SELECT 1/0

SELECT 1/0 with ANSI_WARNINGS ON (the SQL Server default) produces
SQL_SUCCESS_WITH_INFO (a NULL result set + warning), not SQL_ERROR.
This caused the tests to fail across all CI environments because
nextRowset() returned true (valid result set) instead of the expected
false (error).

RAISERROR('...', 16, 1) always produces SQL_ERROR from SQLMoreResults
regardless of ANSI_WARNINGS or ARITHABORT settings, making it a
reliable cross-environment trigger for the mid-batch error path that
this feature is designed to handle.

* Fix PDO flush loops to use silent drain when batch_error_continue is enabled

The PDO execute and param_hook flush loops used throw_on_errors=true
(the default), which means a mid-batch SQL_ERROR from a prior partial
navigation would throw, call SQLCancel, and fail the re-execute.

The sqlsrv driver already handled this correctly with silent drain
(throw_on_errors=false). Apply the same conditional logic to PDO:
when batch_error_continue is enabled, flush silently; otherwise
preserve the existing throwing behavior.

Also adds PDO re-execute tests (Tests 6 and 7) to validate that
re-executing after partial batch navigation works correctly for both
opt-in and default connections.

* Fix PDO 'Invalid cursor state' after SQL_ERROR in opt-in batch continuation

After SQLMoreResults returns SQL_ERROR for a non-result-producing statement
(e.g. RAISERROR), there is no active ODBC cursor. The PDO nextRowset code
unconditionally called SQLNumResultCols/SQLRowCount after core_sqlsrv_next_result,
which failed with 'Invalid cursor state' (SQLSTATE 24000).

Fix:
1. In core_sqlsrv_next_result: when report_errors=true and r==SQL_ERROR,
   clean up the previous result set and return early WITHOUT creating a
   new result set object. The batch remains navigable.
2. In pdo_sqlsrv_stmt_next_rowset: check current_results != NULL before
   calling SQLNumResultCols/SQLRowCount. On error markers (NULL results),
   set column_count=0 and row_count=0.
3. In test: suppress ERRMODE_WARNING output with @ operator so expected
   output stays deterministic across environments.

* Address review nits: extract free_current_results() helper, remove dead assignments

1. Extract the ~12-line current_results teardown block into a
   free_current_results() helper method on sqlsrv_stmt. Used in the
   destructor, new_result_set(), and the SQL_ERROR opt-in path.

2. Remove dead stmt->column_count = 0 / stmt->row_count = 0 assignments
   that were immediately overwritten by clean_up_results_metadata()
   (which sets them to ACTIVE_NUM_COLS_INVALID / ACTIVE_NUM_ROWS_INVALID).

Author: jahnvi480

CHANGELOG.md

@@ -14,6 +14,9 @@ Updated PECL release packages. Here is the list of updates:
 - Support for Red Hat 9 and 10
 - Support for Alpine 3.20, 3.21, 3.22, and 3.23
 - Support for macOS 15 and 26
+- Added opt-in batch error continuation controls for sqlsrv and PDO next-result APIs ([#1599](https://github.com/microsoft/msphpsql/issues/1599))
+  - Applies only when set at connection scope (`BatchErrorContinue` or `PDO::SQLSRV_ATTR_BATCH_ERROR_CONTINUE`)
+  - In opt-in mode, next-result APIs may return success while reporting `SQL_ERROR` diagnostics, allowing callers to continue traversing rowsets
 
 ### Removed
 - Support for PHP 8.1 and 8.2
@@ -35,6 +38,7 @@ Updated PECL release packages. Here is the list of updates:
 - Fixed critical memory safety bugs in encoding conversion - NULL pointer dereference and uninitialized pointer return ([PR #1555](https://github.com/microsoft/msphpsql/pull/1555))
 - Removed lingering error2 reference from failure block in CI pipeline ([PR #1568](https://github.com/microsoft/msphpsql/pull/1568))
 - Fixed PHP 8.5 compatibility issues in tests and CI pipeline ([PR #1569](https://github.com/microsoft/msphpsql/pull/1569))
+- Preserved legacy next-result error semantics by default while allowing opt-in continuation after mid-batch statement errors
 
 ### Limitations
 - No support for inout / output params when using sql_variant type

source/pdo_sqlsrv/pdo_dbh.cpp

@@ -1301,6 +1301,11 @@ bool pdo_sqlsrv_dbh_set_attr(_Inout_ pdo_dbh_t *dbh, _In_ zend_long attr, _Inout
             }
             break;
 
+            case SQLSRV_ATTR_BATCH_ERROR_CONTINUE:
+                // Connection-level option: applies to all statements created by this DBH.
+                driver_dbh->batch_error_continue = zend_is_true(val);
+                break;
+
 #if PHP_VERSION_ID >= 70200
             case PDO_ATTR_DEFAULT_STR_PARAM:
             {
@@ -1525,6 +1530,13 @@ int pdo_sqlsrv_dbh_get_attr(_Inout_ pdo_dbh_t *dbh, _In_ zend_long attr, _Inout_
                 break;
             }
 
+            case SQLSRV_ATTR_BATCH_ERROR_CONTINUE:
+            {
+                // Connection-level option value.
+                ZVAL_BOOL(return_value, driver_dbh->batch_error_continue);
+                break;
+            }
+
 #if PHP_VERSION_ID >= 70200
             case PDO_ATTR_DEFAULT_STR_PARAM:
             {

source/pdo_sqlsrv/pdo_init.cpp

@@ -304,6 +304,7 @@ namespace {
         { "SQLSRV_ATTR_FORMAT_DECIMALS"     , SQLSRV_ATTR_FORMAT_DECIMALS },
         { "SQLSRV_ATTR_DECIMAL_PLACES"      , SQLSRV_ATTR_DECIMAL_PLACES },
         { "SQLSRV_ATTR_DATA_CLASSIFICATION" , SQLSRV_ATTR_DATA_CLASSIFICATION },
+        { "SQLSRV_ATTR_BATCH_ERROR_CONTINUE", SQLSRV_ATTR_BATCH_ERROR_CONTINUE },
 
         // used for the size for output parameters: PDO::PARAM_INT and PDO::PARAM_BOOL use the default size of int,
         // PDO::PARAM_STR uses the size of the string in the variable

source/pdo_sqlsrv/pdo_stmt.cpp

@@ -549,7 +549,12 @@ int pdo_sqlsrv_stmt_execute( _Inout_ pdo_stmt_t *stmt )
 
             while( driver_stmt->past_next_result_end == false ) {
 
-                core_sqlsrv_next_result( driver_stmt, false );
+                // When batch_error_continue is enabled, use silent drain
+                // (throw_on_errors=false) so remaining mid-batch errors
+                // don't prevent re-execution.  Without opt-in, preserve
+                // legacy throwing behavior.
+                core_sqlsrv_next_result( driver_stmt, false,
+                    !driver_stmt->conn->batch_error_continue );
             }
         }
 
@@ -1217,21 +1222,32 @@ int pdo_sqlsrv_stmt_next_rowset( _Inout_ pdo_stmt_t *stmt )
 
         SQLSRV_ASSERT( driver_stmt != NULL, "pdo_sqlsrv_stmt_next_rowset: driver_data object was null" );
 
-        core_sqlsrv_next_result( static_cast<sqlsrv_stmt*>( stmt->driver_data ) );
+        core_sqlsrv_next_result( static_cast<sqlsrv_stmt*>( stmt->driver_data ), true,
+                 !static_cast<sqlsrv_stmt*>( stmt->driver_data )->conn->batch_error_continue,
+                 static_cast<sqlsrv_stmt*>( stmt->driver_data )->conn->batch_error_continue );
 
         if( driver_stmt->past_next_result_end == true ) {
             // Clean up remaining metadata since new_result_set() was not called
             driver_stmt->clean_up_results_metadata();
             return 0;
         }
 
-        stmt->column_count = core::SQLNumResultCols( driver_stmt );
-
-        // return the row count regardless if there are any rows or not
-        stmt->row_count = core::SQLRowCount( driver_stmt );
-
-        driver_stmt->column_count = static_cast<short>(stmt->column_count);
-        driver_stmt->row_count = static_cast<long>(stmt->row_count);
+        // When positioned on an error marker (opt-in batch error continuation
+        // after SQL_ERROR from a non-result-producing statement like RAISERROR),
+        // there is no active ODBC cursor. Skip SQLNumResultCols/SQLRowCount
+        // which would fail with "Invalid cursor state".
+        if( driver_stmt->current_results != NULL ) {
+            stmt->column_count = core::SQLNumResultCols( driver_stmt );
+            stmt->row_count = core::SQLRowCount( driver_stmt );
+            driver_stmt->column_count = static_cast<short>(stmt->column_count);
+            driver_stmt->row_count = static_cast<long>(stmt->row_count);
+        }
+        else {
+            stmt->column_count = 0;
+            stmt->row_count = 0;
+            driver_stmt->column_count = 0;
+            driver_stmt->row_count = 0;
+        }
     }
     catch( core::CoreException& ) {
 
@@ -1305,7 +1321,10 @@ int pdo_sqlsrv_stmt_param_hook( _Inout_ pdo_stmt_t *stmt,
 
                         while( driver_stmt->past_next_result_end == false ) {
 
-                            core_sqlsrv_next_result( driver_stmt, false );
+                            // Match execute flush: silent drain when opt-in is
+                            // enabled, legacy throw otherwise.
+                            core_sqlsrv_next_result( driver_stmt, false,
+                                !driver_stmt->conn->batch_error_continue );
                         }
                     }
 

source/pdo_sqlsrv/php_pdo_sqlsrv_int.h

@@ -90,7 +90,8 @@ enum PDO_SQLSRV_ATTR {
     SQLSRV_ATTR_FETCHES_DATETIME_TYPE,
     SQLSRV_ATTR_FORMAT_DECIMALS,
     SQLSRV_ATTR_DECIMAL_PLACES,
-    SQLSRV_ATTR_DATA_CLASSIFICATION
+    SQLSRV_ATTR_DATA_CLASSIFICATION,
+    SQLSRV_ATTR_BATCH_ERROR_CONTINUE
 };
 
 // valid set of values for TransactionIsolation connection option

source/shared/core_sqlsrv.h

@@ -1135,6 +1135,7 @@ struct sqlsrv_conn : public sqlsrv_context {
 
     col_encryption_option ce_option;    // holds the details of what are required to enable column encryption
     ODBC_DRIVER driver_version;         // version of ODBC driver
+    bool batch_error_continue;          // opt-in to continue past mid-batch SQLMoreResults errors
 
     ACCESSTOKEN* azure_ad_access_token;  // non-owning; managed by token cache
 
@@ -1144,6 +1145,7 @@ struct sqlsrv_conn : public sqlsrv_context {
     {
         server_version = SERVER_VERSION_UNKNOWN;
         driver_version = ODBC_DRIVER::VER_UNKNOWN;
+        batch_error_continue = false;
         azure_ad_access_token = nullptr;
     }
 
@@ -1696,6 +1698,9 @@ struct sqlsrv_stmt : public sqlsrv_context {
     // free sensitivity classification metadata
     void clean_up_sensitivity_metadata();
 
+    // free the current result set object (if any)
+    void free_current_results();
+
     // free resultset metadata
     void clean_up_results_metadata();
 
@@ -1805,7 +1810,8 @@ void core_sqlsrv_get_field( _Inout_ sqlsrv_stmt* stmt, _In_ SQLUSMALLINT field_i
                             _Outref_result_bytebuffer_maybenull_(*field_length) void*& field_value, _Inout_ SQLLEN* field_length, _In_ bool cache_field,
                             _Out_ SQLSRV_PHPTYPE *sqlsrv_php_type_out);
 bool core_sqlsrv_has_any_result( _Inout_ sqlsrv_stmt* stmt );
-void core_sqlsrv_next_result( _Inout_ sqlsrv_stmt* stmt, _In_ bool finalize_output_params = true, _In_ bool throw_on_errors = true );
+void core_sqlsrv_next_result( _Inout_ sqlsrv_stmt* stmt, _In_ bool finalize_output_params = true, _In_ bool throw_on_errors = true,
+                              _In_ bool report_errors = false );
 void core_sqlsrv_set_scrollable( _Inout_ sqlsrv_stmt* stmt, _In_ unsigned long cursor_type );
 void core_sqlsrv_set_query_timeout( _Inout_ sqlsrv_stmt* stmt, _Inout_ zval* value_z );
 bool core_sqlsrv_send_stream_packet( _Inout_ sqlsrv_stmt* stmt, _In_opt_ bool get_all = false);

source/shared/core_stmt.cpp

@@ -18,6 +18,7 @@
 //---------------------------------------------------------------------------------------------------------------------------------
 
 #include "core_sqlsrv.h"
+#include "zend_exceptions.h"
 
 #include <sstream>
 #include <vector>
@@ -153,12 +154,7 @@ sqlsrv_stmt::~sqlsrv_stmt( void )
         close_active_stream( this );
     }
 
-    // delete any current results
-    if( current_results ) {
-        current_results->~sqlsrv_result_set();
-        efree( current_results );
-        current_results = NULL;
-    }
+    free_current_results();
 
     // delete sensivity data
     clean_up_sensitivity_metadata();
@@ -183,6 +179,16 @@ void sqlsrv_stmt::free_param_data( void )
     zend_hash_clean( Z_ARRVAL( field_cache ));
 }
 
+// free the current result set object without creating a new one.
+void sqlsrv_stmt::free_current_results( void )
+{
+    if( current_results ) {
+        current_results->~sqlsrv_result_set();
+        efree( current_results );
+        current_results = NULL;
+    }
+}
+
 
 // to be called whenever a new result set is created, such as after an
 // execute or next_result.  Resets the state variables.
@@ -197,12 +203,7 @@ void sqlsrv_stmt::new_result_set( void )
     this->column_count = ACTIVE_NUM_COLS_INVALID;
     this->row_count = ACTIVE_NUM_ROWS_INVALID;
 
-    // delete any current results
-    if( current_results ) {
-        current_results->~sqlsrv_result_set();
-        efree( current_results );
-        current_results = NULL;
-    }
+    free_current_results();
 
     // delete sensivity data
     clean_up_sensitivity_metadata();
@@ -963,7 +964,7 @@ bool core_sqlsrv_has_any_result( _Inout_ sqlsrv_stmt* stmt )
 // Returns
 // Nothing, exception thrown if problem occurs
 
-void core_sqlsrv_next_result( _Inout_ sqlsrv_stmt* stmt, _In_ bool finalize_output_params, _In_ bool throw_on_errors )
+void core_sqlsrv_next_result( _Inout_ sqlsrv_stmt* stmt, _In_ bool finalize_output_params, _In_ bool throw_on_errors, _In_ bool report_errors )
 {
     try {
 
@@ -982,11 +983,59 @@ void core_sqlsrv_next_result( _Inout_ sqlsrv_stmt* stmt, _In_ bool finalize_outp
         zend_hash_clean( Z_ARRVAL( stmt->col_cache ));
 
         SQLRETURN r;
+
         if( throw_on_errors ) {
+            // Use the throwing wrapper for callers that require fail-fast
+            // behavior on SQL_ERROR.
             r = core::SQLMoreResults( stmt );
         }
         else {
-            r = SQLMoreResults( stmt->handle() );
+            // Non-throwing paths are split into two semantics:
+            // 1. Silent internal drain (report_errors=false): do not throw and
+            //    do not push diagnostics to the PHP error queues.
+            // 2. User-facing opt-in continuation (report_errors=true): report
+            //    SQL_ERROR / SQL_SUCCESS_WITH_INFO without throwing so callers
+            //    can continue to subsequent rowsets.
+            r = ::SQLMoreResults( stmt->handle() );
+
+            SQLSRV_ASSERT( r != SQL_INVALID_HANDLE, "Invalid handle returned from SQLMoreResults." );
+
+            if( report_errors ) {
+                if( r == SQL_ERROR ) {
+                    // In opt-in continuation mode we surface diagnostics and
+                    // keep rowset navigation alive. Depending on server/session
+                    // state, SQL_ERROR can represent either a recoverable
+                    // mid-batch statement failure or a fatal transport-level
+                    // condition.
+                    call_error_handler( stmt, SQLSRV_ERROR_ODBC, /*warning*/0 );
+
+                    // The PDO error handler may set a pending zend exception
+                    // in ERRMODE_EXCEPTION. Clear it so next-result traversal
+                    // can continue and the error remains observable via
+                    // errorInfo()/sqlsrv_errors().
+                    if( EG(exception) != NULL ) {
+                        zend_clear_exception();
+                    }
+
+                    // SQL_ERROR from a non-result-producing statement (e.g.
+                    // RAISERROR) leaves no active ODBC cursor. Clean up the
+                    // previous result set but do NOT create a new one — calling
+                    // SQLNumResultCols/SQLRowCount would fail with "Invalid
+                    // cursor state". The batch remains navigable via subsequent
+                    // next-result calls.
+                    stmt->free_current_results();
+                    stmt->fetch_called = false;
+                    stmt->has_rows = false;
+                    stmt->past_fetch_end = false;
+                    stmt->last_field_index = -1;
+                    stmt->clean_up_sensitivity_metadata();
+                    stmt->clean_up_results_metadata();
+                    return;
+                }
+                else if( r == SQL_SUCCESS_WITH_INFO ) {
+                    call_error_handler( stmt, SQLSRV_ERROR_ODBC, /*warning*/1 );
+                }
+            }
         }
 
         if( r == SQL_NO_DATA ) {
@@ -1005,7 +1054,15 @@ void core_sqlsrv_next_result( _Inout_ sqlsrv_stmt* stmt, _In_ bool finalize_outp
     }
     catch( core::CoreException& e ) {
 
-        SQLCancel( stmt->handle() );
+        // For internal callers (throw_on_errors=true — flush loops,
+        // closeCursor, param binding) we still call SQLCancel to clean up
+        // the ODBC handle on error.  For user-facing callers
+        // (throw_on_errors=false — sqlsrv_next_result / PDO::nextRowset)
+        // we must NOT cancel because the handle is still valid and the
+        // batch remains navigable after a mid-batch statement failure.
+        if( throw_on_errors ) {
+            SQLCancel( stmt->handle() );
+        }
         throw e;
     }
 }

source/sqlsrv/conn.cpp

@@ -72,6 +72,14 @@ struct decimal_places_func
     }
 };
 
+struct batch_error_continue_func
+{
+    static void func(connection_option const* /*option*/, _In_ zval* value, _Inout_ sqlsrv_conn* conn, std::string& /*conn_str*/)
+    {
+        conn->batch_error_continue = zend_is_true(value);
+    }
+};
+
 
 struct conn_char_set_func {
 
@@ -231,6 +239,7 @@ const char DecimalPlaces[] = "DecimalPlaces";
 const char FormatDecimals[] = "FormatDecimals";
 const char DateAsString[] = "ReturnDatesAsStrings";
 const char Driver[] = "Driver";
+const char BatchErrorContinue[] = "BatchErrorContinue";
 const char Encrypt[] = "Encrypt";
 const char Failover_Partner[] = "Failover_Partner";
 const char KeyStoreAuthentication[] = "KeyStoreAuthentication";
@@ -256,6 +265,7 @@ const char HostNameInCertificate[] = "HostNameInCertificate";
 enum SS_CONN_OPTIONS {
 
     SS_CONN_OPTION_DATE_AS_STRING = SQLSRV_CONN_OPTION_DRIVER_SPECIFIC,
+    SS_CONN_OPTION_BATCH_ERROR_CONTINUE,
     SS_CONN_OPTION_FORMAT_DECIMALS,
     SS_CONN_OPTION_DECIMAL_PLACES,
 };
@@ -577,6 +587,15 @@ const connection_option SS_CONN_OPTS[] = {
         CONN_ATTR_BOOL,
         date_as_string_func::func
     },
+    {
+        SSConnOptionNames::BatchErrorContinue,
+        sizeof( SSConnOptionNames::BatchErrorContinue ),
+        SS_CONN_OPTION_BATCH_ERROR_CONTINUE,
+        SSConnOptionNames::BatchErrorContinue,
+        sizeof( SSConnOptionNames::BatchErrorContinue ),
+        CONN_ATTR_BOOL,
+        batch_error_continue_func::func
+    },
     {
         SSConnOptionNames::FormatDecimals,
         sizeof( SSConnOptionNames::FormatDecimals),

source/sqlsrv/stmt.cpp

@@ -569,7 +569,7 @@ PHP_FUNCTION( sqlsrv_next_result )
 
     try {
 
-        core_sqlsrv_next_result( stmt, true );
+        core_sqlsrv_next_result( stmt, true, !stmt->conn->batch_error_continue, stmt->conn->batch_error_continue );
 
         if( stmt->past_next_result_end ) {
             // Clean up remaining metadata since new_result_set() was not called