Функция SQLRowCount
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLRowCount возвращает количество строк, затронутых инструкцией UPDATE, INSERT или DELETE ; операцию SQL_ADD, SQL_UPDATE_BY_BOOKMARK или SQL_DELETE_BY_BOOKMARK в SQLBulkOperations; или операцию SQL_UPDATE или SQL_DELETE в SQLSetPos.
Синтаксис
SQLRETURN SQLRowCount(
SQLHSTMT StatementHandle,
SQLLEN * RowCountPtr);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
RowCountPtr
[Выходные данные] Указывает на буфер, в котором возвращается число строк. Для инструкций UPDATE, INSERT и DELETE для операций SQL_ADD, SQL_UPDATE_BY_BOOKMARK и SQL_DELETE_BY_BOOKMARK в SQLBulkOperations, а для операций SQL_UPDATE или SQL_DELETE в SQLSetPos значение, возвращаемое в *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, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLRowCount и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLRowCount . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) Функция была вызвана до вызова SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos для ОператораHandle. (DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
Комментарии
Если последняя инструкция SQL, выполняемая в дескрипторе инструкции, не была инструкцией UPDATE, INSERT или DELETE, либо если аргумент операции в предыдущем вызове SQLBulkOperations не был SQL_ADD, SQL_UPDATE_BY_BOOKMARK или SQL_DELETE_BY_BOOKMARK или если аргумент операции в предыдущем вызове SQLSetPos не был SQL_UPDATE или SQL_DELETE, Значение *RowCountPtr определяется драйвером. Дополнительные сведения см. в разделе "Определение числа затронутых строк".
Связанные функции
| Сведения | Смотрите |
|---|---|
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |