Функция 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	Error	Description
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 , не поддерживает функцию.

Комментарии

Имена курсоров используются только в операторах обновления и удаления (например, updatetable-name ...WHERE CURRENT OFcursor-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