Функция SQLGetCursorName
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLGetCursorName возвращает имя курсора, связанное с указанной инструкцией.
Синтаксис
SQLRETURN SQLGetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
CursorName
[Выходные данные] Указатель на буфер, в котором возвращается имя курсора.
Если cursorName имеет значение NULL, NameLengthPtr по-прежнему возвращает общее количество символов (за исключением символа завершения null для символьных данных), доступное для возврата в буфер, на который указывает CursorName.
BufferLength
[Входные данные] Длина *CursorName в символах.
NameLengthPtr
[Выходные данные] Указатель на память, в которой возвращается общее количество символов (за исключением символа завершения null), доступное для возврата в *CursorName. Если число символов, доступных для возврата, больше или равно BufferLength, имя курсора в *CursorName усечено до BufferLength минус длина символа завершения null.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLGetCursorName возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с handleType SQL_HANDLE_STMT и дескриптором инструкцииHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLGetCursorName и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемых диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01004 | Строковые данные, усеченные справа | Буфер *CursorName был недостаточно большим, чтобы вернуть все имя курсора, поэтому имя курсора было усечено. Длина ненадежного имени курсора возвращается в *NameLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLGetCursorName . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY015 | Имя курсора недоступно | (DM) Драйвер был драйвером ODBC 2*.x*, не было открытого курсора в инструкции, и имя курсора не было задано с sqlSetCursorName. |
| HY090 | Недопустимая длина строки или буфера | (DM) Значение, указанное в аргументе BufferLength , было меньше 0. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
Комментарии
Имена курсоров используются только в операторах обновления и удаления (например, update table-name ...WHERE CURRENT OF cursor-name). Дополнительные сведения см. в разделе "Позиционированные обновления" и "Удаление инструкций". Если приложение не вызывает SQLSetCursorName для определения имени курсора, драйвер создает имя. Это имя начинается с букв SQL_CUR.
Примечание.
В ODBC 2*.x*, когда не было открытого курсора и имя не было задано вызовом SQLSetCursorName, вызов SQLGetCursorName вернул SQLSTATE HY015 (имя курсора недоступно). В ODBC 3*.x*, это больше не верно; независимо от того, когда вызывается SQLGetCursorName , драйвер возвращает имя курсора.
SQLGetCursorName возвращает имя курсора независимо от того, было ли создано имя явно или неявно. Имя курсора неявно создается, если SQLSetCursorName не вызывается. SQLSetCursorName можно вызвать для переименования курсора в инструкции, если курсор находится в выделенном или подготовленном состоянии.
Имя курсора, заданное явно или неявно, остается заданным до тех пор, пока оператор StatementHandle, с которым он связан, с помощью SQLFreeHandle с handleType SQL_HANDLE_STMT.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Подготовка инструкции для выполнения | Функция SQLPrepare |
| Задание имени курсора | Функция SQLSetCursorName |