Функция 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 | Error | Description |
|---|---|---|
| 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 , не поддерживает функцию. |
Комментарии
Имена курсоров используются только в операторах обновления и удаления (например, updatetable-name ...WHERE CURRENT OFcursor-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 |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по