SQLRowCount 函式

  • 發行項

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

摘要
SQLRowCount 會傳回受 UPDATE 、 INSERT 或 DELETE 語句影響的資料列數目;SQLBulkOperations 中 SQL_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作業，以及 SQLSetPos 中 SQL_UPDATE或SQL_DELETE作業的 UPDATE 、INSERT 和 DELETE 語句，* RowCountPtr 中傳回的值可能是要求所影響的資料列數目，如果受影響的資料列數目無法使用，則為 -1。

當 呼叫 SQLExecute 、 SQLExecDirect 、SQLBulkOperations 、 SQLSetPos 或 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時 ，藉由呼叫 SQLGetDiagRec 與 handletype 為 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 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。

（DM） 在呼叫語句Handle 的 SQLExecute 、SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos 之前呼叫函式。

（DM） 呼叫 StatementHandle 的非同步執行函式，並在呼叫此函式時仍在執行。

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

註解

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

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

另請參閱

ODBC API 參考
ODBC 標頭檔