SQLSetCursorName, funkcja

zgodności
Wersja wprowadzona: Zgodność ze standardami ODBC 1.0: ISO 92

podsumowania
SQLSetCursorName kojarzy nazwę kursora z aktywną instrukcją. Jeśli aplikacja nie wywołuje SQLSetCursorName, sterownik generuje nazwy kursorów zgodnie z potrzebami na potrzeby przetwarzania instrukcji SQL.

Składnia

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

Argumenty

, instrukcjaHandle
[Dane wejściowe] Uchwyt instrukcji.

CursorName
[Dane wejściowe] Nazwa kursora. W celu wydajnego przetwarzania nazwa kursora nie powinna zawierać żadnych spacji wiodących ani końcowych w nazwie kursora, a jeśli nazwa kursora zawiera identyfikator rozdzielany, ogranicznik powinien być umieszczony jako pierwszy znak w nazwie kursora.

NameLength
[Dane wejściowe] Długość znaków *CursorName.

Zwraca

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR lub SQL_INVALID_HANDLE.

Diagnostyka

Gdy sqlSetCursorName zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, skojarzona wartość SQLSTATE może zostać uzyskana przez wywołanie SQLGetDiagRec za pomocą typu HandleType SQL_HANDLE_STMT oraz StatementHandle. W poniższej tabeli wymieniono wartości SQLSTATE, które są często zwracane przez SQLSetCursorName i objaśniono poszczególne wartości w kontekście tej funkcji; notacja "(DM)" poprzedza opisy obiektów SQLSTATEs zwróconych przez menedżera sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.

Komentarze

Nazwy kursorów są używane tylko w instrukcjach aktualizacji i usuwania umieszczonych (na przykład UPDATEnazwa tabeli ...GDZIE BIEŻĄCA NAZWA kursora). Aby uzyskać więcej informacji, zobacz Instrukcje aktualizacji i usuwania. Jeśli aplikacja nie wywołuje SQLSetCursorName w celu zdefiniowania nazwy kursora, podczas wykonywania instrukcji zapytania sterownik generuje nazwę rozpoczynającą się od liter SQL_CUR i nie przekracza 18 znaków.

Wszystkie nazwy kursorów w ramach połączenia muszą być unikatowe. Maksymalna długość nazwy kursora jest definiowana przez sterownik. W przypadku maksymalnej współdziałania zaleca się, aby aplikacje ograniczały nazwy kursorów do nie więcej niż 18 znaków. W formacie ODBC 3*.x*, jeśli nazwa kursora jest identyfikatorem cytowanym, jest traktowana w sposób uwzględniający wielkość liter i może zawierać znaki, na które składnia języka SQL nie zezwala lub traktuje się specjalnie, na przykład puste lub zastrzeżone słowa kluczowe. Jeśli nazwa kursora musi być traktowana w sposób uwzględniający wielkość liter, musi zostać przekazana jako identyfikator cytowany.

Nazwa kursora ustawiana jawnie lub niejawnie pozostaje ustawiona do momentu porzucenia instrukcji, z którą jest skojarzona, przy użyciu SQLFreeHandle. SQLSetCursorName można wywołać, aby zmienić nazwę kursora na instrukcji, o ile kursor jest w stanie przydzielonym lub przygotowanym.

Przykład kodu

W poniższym przykładzie aplikacja używa SQLSetCursorName, aby ustawić nazwę kursora dla instrukcji. Następnie używa tej instrukcji do pobierania wyników z tabeli CUSTOMERS. Na koniec wykonuje aktualizację umieszczoną w celu zmiany numeru telefonu Johna Smitha. Należy pamiętać, że aplikacja używa różnych dojść instrukcji dla instrukcji SELECT i UPDATE instrukcji.

Aby zapoznać się z innym przykładem kodu, zobacz 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);  
}  

Powiązane funkcje

Zobacz też

dokumentacja interfejsu API ODBC
plików nagłówków ODBC