Функция 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, если не указано иное.

Комментарии

Имена курсоров используются только в операторах обновления и удаления (например, 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);  
}  

Связанные функции

См. также

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