Функция 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

См. также

Справочник по API ODBC
Файлы заголовков ODBC