Функция SQLMoreResults
Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: ODBC
Сводка
SQLMoreResults определяет, доступны ли дополнительные результаты в инструкции, содержащей инструкции SELECT, UPDATE, INSERT или DELETE, и, если да, инициализирует обработку этих результатов.
Синтаксис
SQLRETURN SQLMoreResults(
SQLHSTMT StatementHandle);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE ИЛИ SQL_PARAM_DATA_AVAILABLE.
Диагностика
Когда SQLMoreResults возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, часто возвращаемые SQLMoreResults , и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемых диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Значение параметра изменилось | Значение атрибута инструкции изменилось по мере обработки пакета. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 40001 | Сбой сериализации | Транзакция была откатена из-за взаимоблокировки ресурсов с другой транзакцией. |
| 40003 | Неизвестное завершение инструкции | Связанное подключение завершилось сбоем во время выполнения этой функции, и состояние транзакции невозможно определить. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция SQLMoreResults была вызвана и до завершения выполнения sqlCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция SQLMoreResults снова была вызвана на ОператорHandle. Функция SQLMoreResults была вызвана и, прежде чем завершить выполнение, SQLCancel или SQLCancelHandle был вызван в ОператорHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLMoreResults . (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 , не поддерживает функцию. |
| IM017 | Опрос отключен в асинхронном режиме уведомлений | При использовании модели уведомлений опрос отключается. |
| IM018 | SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. | Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
Операторы SELECT возвращают результирующие наборы. Инструкции UPDATE, INSERT и DELETE возвращают количество затронутых строк. Если любая из этих инструкций пакетна, отправляется с массивами параметров (нумерованным в порядке увеличения порядка параметров, в том порядке, в котором они отображаются в пакете), или в процедурах, они могут возвращать несколько результирующих наборов или счетчиков строк. Сведения о пакетах инструкций и массивов параметров см. в пакетах инструкций SQL и массивах значений параметров.
После выполнения пакета приложение размещается в первом результирующем наборе. Приложение может вызывать SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos и все функции метаданных для первых или любых последующих результирующих наборов, так же как и только один результирующий набор. После завершения работы с первым результирующий набор приложение вызывает SQLMoreResults , чтобы перейти к следующему результирующий набор. Если доступен другой результирующий набор или число, SQLMoreResults возвращает SQL_SUCCESS и инициализирует результирующий набор или число для дополнительной обработки. Если между операторами создания результирующих наборов отображаются какие-либо инструкции подсчета строк, их можно выполнить путем вызова SQLMoreResults. После вызова инструкций SQLMoreResults для UPDATE, INSERT или DELETE приложение может вызывать SQLRowCount.
Если был текущий результирующий набор с неуправляемыми строками, SQLMoreResults удаляет результирующий набор и делает следующий результирующий набор или число доступным. Если все результаты обработаны, SQLMoreResults возвращает SQL_NO_DATA. Для некоторых драйверов выходные параметры и возвращаемые значения недоступны, пока не будут обработаны все результирующие наборы и счетчики строк. Для таких драйверов выходные параметры и возвращаемые значения становятся доступными, когда SQLMoreResults возвращает SQL_NO_DATA.
Все привязки, которые были установлены для предыдущего результирующий набор, по-прежнему остаются допустимыми. Если структуры столбцов отличаются для этого результируемого набора, вызов SQLFetch или SQLFetchScroll может привести к ошибке или усечению. Чтобы предотвратить это, приложению необходимо вызвать SQLBindCol для явной повторной привязки (или сделать это, задав дескрипторные поля). Кроме того, приложение может вызывать SQLFreeStmt с параметром SQL_UNBIND для отмены привязки всех буферов столбцов.
Значения атрибутов инструкции, такие как тип курсора, параллелизм курсоров, размер набора ключей или максимальная длина, могут изменяться по мере перехода приложения через пакет путем вызовов SQLMoreResults. В этом случае SQLMoreResults вернет SQL_SUCCESS_WITH_INFO и SQLSTATE 01S02 (значение параметра изменилось).
Вызов SQLCloseCursor или SQLFreeStmt с параметром SQL_CLOSE удаляет все результирующие наборы и количество строк, доступные в результате выполнения пакета. Дескриптор инструкции возвращается в выделенное или подготовленное состояние. Вызов SQLCancel для отмены асинхронной выполняемой функции при выполнении пакета, а дескриптор инструкции находится в выполняемом, расположенном курсором или асинхронном состоянии, приводит ко всем наборам результатов и счетчикам строк, созданным пакетом, если вызов отмены выполнен успешно. Затем инструкция возвращается в подготовленное или выделенное состояние.
Если пакет инструкций или процедура смешивает другие инструкции SQL с инструкциями SELECT, UPDATE, INSERT и DELETE, эти другие инструкции не влияют на SQLMoreResults.
Дополнительные сведения см. в разделе "Несколько результатов".
Если выполнен поиск по обновлению, вставке или удалению инструкции в пакете инструкций не влияет ни на какие строки в источнике данных, SQLMoreResults возвращает SQL_SUCCESS. Это отличается от случая поиска, вставки или удаления инструкции, выполняемой с помощью SQLExecDirect, SQLExecute или SQLParamData, которая возвращает SQL_NO_DATA, если она не влияет на строки в источнике данных. Если приложение вызывает SQLRowCount, чтобы получить количество строк после вызова SQLMoreResults, не повлияло ни на какие строки, SQLRowCount вернет SQL_NO_DATA.
Дополнительные сведения о допустимой последовательности функций обработки результатов см . в приложении B: таблицы перехода состояния ODBC.
Дополнительные сведения о SQL_PARAM_DATA_AVAILABLE и потоковых выходных параметрах см. в разделе "Получение выходных параметров с помощью SQLGetData".
Доступность счетчиков строк
Если пакет содержит несколько последовательных инструкций, создаваемых числом строк, возможно, эти счетчики строк свернуты в только одно число строк. Например, если пакет содержит пять инструкций вставки, некоторые источники данных могут возвращать пять отдельных счетчиков строк. Некоторые другие источники данных возвращают только одно число строк, представляющее сумму пяти отдельных строк.
Если пакет содержит сочетание инструкций создания результирующих наборов и инструкций подсчета строк, количество строк может быть недоступно вообще. Поведение драйвера относительно доступности счетчиков строк перечисляется в типе сведений SQL_BATCH_ROW_COUNT, доступном через вызов SQLGetInfo. Например, предположим, что пакет содержит элемент SELECT, за которым следует два элемента INSERTи другой SELECT. Затем возможны следующие случаи:
Количество строк, соответствующих двум операторам INSERT , не доступно вообще. Первый вызов SQLMoreResults будет размещать вас в результирующем наборе второго оператора SELECT .
Количество строк, соответствующих двум операторам INSERT , доступно по отдельности. (Вызов SQLGetInfo не возвращает SQL_BRC_ROLLED_UP бит для типа сведений SQL_BATCH_ROW_COUNT.) Первый вызов SQLMoreResults будет размещать вас на количестве строк первого INSERT, а второй вызов будет размещать вас на количестве строк второго INSERT. Третий вызов SQLMoreResults будет размещать вас в результирующем наборе второго оператора SELECT .
Количество строк, соответствующих двум INSERTs , свернуто в один число строк, доступных. (Вызов SQLGetInfo возвращает SQL_BRC_ROLLED_UP бит для типа сведений SQL_BATCH_ROW_COUNT.) Первый вызов SQLMoreResults будет размещать вас в свернутом количестве строк, а второй вызов SQLMoreResults будет размещать вас в результирующем наборе второго SELECT.
Некоторые драйверы делают количество строк доступными только для явных пакетов, а не для хранимых процедур.
Связанные функции
| Сведения | Раздел |
|---|---|
| Отмена обработки инструкций | Функция SQLCancel |
| Получение блока данных или прокрутка результирующий набор | Функция SQLFetchScroll |
| Получение одной строки или блока данных в направлении только для пересылки | Функция SQLFetch |
| Извлечение части или всех столбцов данных | Функция SQLGetData |
См. также
Справочник по API ODBC
Файлы заголовков ODBC
Получение выходных параметров с помощью метода SQLGetData