分享方式:


SQLRowCount 函式

一致性
引進版本:ODBC 1.0 標準合規性:ISO 92

摘要
SQLRowCount 會傳回受 UPDATEINSERTDELETE 語句影響的數據列數目;SQLBulkOperationsSQL_ADD、SQL_UPDATE_BY_BOOKMARK或SQL_DELETE_BY_BOOKMARK作業;或 SQLSetPos 中的SQL_UPDATE或SQL_DELETE作業。

語法

  
SQLRETURN SQLRowCount(  
      SQLHSTMT   StatementHandle,  
      SQLLEN *   RowCountPtr);  

引數

StatementHandle
[輸入]語句句柄。

RowCountPtr
[輸出]指向要在其中傳回數據列計數的緩衝區。 針對 SQLBulkOperations 中SQL_ADD、SQL_UPDATE_BY_BOOKMARK和SQL_DELETE_BY_BOOKMARK作業,以及 SQLSetPosSQL_UPDATE或SQL_DELETE作業的 UPDATE、INSERTDELETE 語句,*RowCountPtr 中傳回的值可能是要求所影響的數據列數目,如果受影響的數據列數目無法使用,則為 -1。

呼叫 SQLExecuteSQLExecDirect、SQLBulkOperationsSQLSetPos 或 SQLMoreResults 時,診斷數據結構的SQL_DIAG_ROW_COUNT欄位會設定為數據列計數,並以實作相依的方式快取數據列計數。 SQLRowCount 會傳回快取的數據列計數值。 快取的數據列計數值有效,直到語句句柄設定回已備妥或已配置的狀態、重新執行語句,或 呼叫 SQLCloseCursor 為止。 請注意,如果自已設定SQL_DIAG_ROW_COUNT欄位之後呼叫函式,SQLRowCount回的值可能會與SQL_DIAG_ROW_COUNT欄位中的值不同,因為SQL_DIAG_ROW_COUNT欄位會由任何函數調用重設為 0。

對於其他語句和函式,驅動程式可以定義 *RowCountPtr 中傳回的值。 例如,某些數據源在擷取數據列之前,可以傳回 SELECT 語句或目錄函式傳回的數據列數目。

注意

許多數據源在擷取結果集之前,無法傳回結果集中的數據列數目;為了達到最大互操作性,應用程式不應該依賴此行為。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLRowCount 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時,藉由呼叫 SQLGetDiagRechandletype 為 SQL_HANDLE_STMT 和 StatementHandle 的 HandleHandle,即可取得相關聯的 SQLSTATE 值。 下表列出 SQLRowCount 通常傳回的 SQLSTATE 值,並說明此函式內容中的每個值;表示法 “(DM)” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明,否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 (函式會傳回SQL_SUCCESS_WITH_INFO。)
HY000 一般錯誤 發生錯誤,其中沒有特定的 SQLSTATE,也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY010 函式順序錯誤 (DM) 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLRowCount 函式時,這個異步函式仍在執行中。

(DM) 已針對 StatementHandle 呼叫 SQLExecuteSQLExecDirectSQLMoreResults,並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前,會呼叫此函式。

(DM) 在呼叫語句Handle 的 SQLExecute、SQLExecDirectSQLBulkOperationsSQLSetPos 之前呼叫函式。

(DM) 呼叫 StatementHandle 的異步執行函式,並在呼叫此函式時仍在執行。

(DM) 已針對 StatementHandle 呼叫 SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos,並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前,會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫,因為基礎記憶體物件無法存取,可能是因為記憶體不足的情況。
HY117 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 (DM) 如需暫停狀態的詳細資訊,請參閱 SQLEndTran 函式
HYT01 已超過連線逾時 在數據源回應要求之前,連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定,SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 (DM) 與 StatementHandle 相關聯的驅動程式不支援 函式。

註解

如果在語句句柄上執行的最後一個 SQL 語句不是 UPDATEINSERTDELETE 語句,或者先前對 SQLBulkOperations 呼叫中的 Operation 自變數未SQL_ADD、SQL_UPDATE_BY_BOOKMARK或SQL_DELETE_BY_BOOKMARK,或先前對 SQLSetPosOperation 自變數未SQL_UPDATE或SQL_DELETE,則為 *RowCountPtr 的值是驅動程式定義的。 如需詳細資訊,請參閱判斷受影響的資料列數目

如需下列資訊 請參閱
執行 SQL 語句 SQLExecDirect 函式
執行備妥的 SQL 語句 SQLExecute 函式

另請參閱

ODBC API 參考
ODBC 標頭檔