Поделиться через

Функция SQLSetCursorName

  • Статья

Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92

Сводка
SQLSetCursorName связывает имя курсора с активной инструкцией. Если приложение не вызывает SQLSetCursorName, драйвер создает имена курсоров при необходимости для обработки инструкций SQL.

Синтаксис

  
SQLRETURN SQLSetCursorName(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CursorName,  
     SQLSMALLINT   NameLength);

Аргументы

ОператорHandle
[Входные данные] Дескриптор инструкции.

CursorName
[Входные данные] Имя курсора. Для эффективной обработки имя курсора не должно содержать начальные или конечные пробелы в имени курсора, а если имя курсора содержит идентификатор с разделителями, разделитель должен быть позиционирован в качестве первого символа в имени курсора.

NameLength
[Входные данные] Длина символов *CursorName.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Когда SQLSetCursorName возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLSetCursorName и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE Ошибка Описание
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004 Строковые данные, усеченные справа Имя курсора превысило максимальное ограничение, поэтому использовалось только максимально допустимое число символов.
24000 Недопустимое состояние курсора Инструкция, соответствующая Оператору StatementHandle , уже находилась в выполняемом или расположенном курсором состоянии.
34000 Недопустимое имя курсора Имя курсора, указанное в *CursorName , было недопустимым, так как оно превысило максимальную длину, определяемую драйвером, или началось с "SQLCUR" или "SQL_CUR".
3C000 Повторяющееся имя курсора Имя курсора, указанное в *CursorName , уже существует.
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY009 Недопустимое использование указателя NULL (DM) Аргумент CursorName был пустым указателем.
HY010 Ошибка последовательности функций (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта анчхронная функция по-прежнему выполнялась при вызове функции SQLSetCursorName .

(DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090 Недопустимая длина строки или буфера (DM) Аргумент NameLength был меньше 0, но не равен SQL_NTS.
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01 Время ожидания для подключения истекло Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Драйвер не поддерживает эту функцию (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию.

Комментарии

Имена курсоров используются только в операторах обновления и удаления (например, update table-name ...WHERE CURRENT OF cursor-name). Дополнительные сведения см. в разделе "Позиционированные обновления" и "Удаление инструкций". Если приложение не вызывает SQLSetCursorName для определения имени курсора, при выполнении инструкции запроса драйвер создает имя, которое начинается с букв SQL_CUR и не превышает 18 символов в длину.

Все имена курсоров в соединении должны быть уникальными. Максимальная длина имени курсора определяется драйвером. Для максимальной совместимости рекомендуется ограничить имена курсоров приложениями не более 18 символов. В ODBC 3*.x*, если имя курсора является идентификатором кавычки, оно обрабатывается в регистре с учетом регистра и может содержать символы, которые синтаксис SQL не позволит или будет обрабатывать специально, например пустые или зарезервированные ключевые слова. Если имя курсора должно обрабатываться с учетом регистра, оно должно быть передано в качестве идентификатора кавычки.

Имя курсора, задающее явно или неявно, остается заданным, пока не будет удалена инструкция, с которой она связана, с помощью SQLFreeHandle. SQLSetCursorName можно вызвать для переименования курсора в инструкции, если курсор находится в выделенном или подготовленном состоянии.

Пример кода

В следующем примере приложение использует SQLSetCursorName для задания имени курсора для инструкции. Затем он использует этот оператор для получения результатов из таблицы CUSTOMERS. Наконец, он выполняет позиционированные обновления, чтобы изменить номер телефона Джона Смита. Обратите внимание, что приложение использует различные дескрипторы инструкций SELECT и UPDATE .

Другой пример кода см . в разделе SQLSetPos.

#define NAME_LEN 50  
#define PHONE_LEN 10  
  
SQLHSTMT     hstmtSelect,  
SQLHSTMT     hstmtUpdate;  
SQLRETURN    retcode;  
SQLHDBC      hdbc;  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   cbName, cbPhone;  
  
/* Allocate the statements and set the cursor name. */  
  
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);  
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);  
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);  
  
/* SELECT the result set and bind its columns to local buffers. */  
  
SQLExecDirect(hstmtSelect,  
      "SELECT NAME, PHONE FROM CUSTOMERS",  
      SQL_NTS);  
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);  
  
/* Read through the result set until the cursor is */  
/* positioned on the row for John Smith. */  
  
do  
 retcode = SQLFetch(hstmtSelect);  
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&  
   (strcmp(szName, "Smith, John") != 0));  
  
/* Perform a positioned update of John Smith's name. */  
  
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
   SQLExecDirect(hstmtUpdate,  
   "UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",  
   SQL_NTS);  
}
Сведения Смотрите
Выполнение инструкции SQL Функция SQLExecDirect
Выполнение подготовленной инструкции SQL Функция SQLExecute
Возврат имени курсора Функция SQLGetCursorName
Настройка параметров прокрутки курсора Функция SQLSetScrollOptions

См. также

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