SQLSetCursorName-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92

Zusammenfassung
SQLSetCursorName ordnet einen Cursornamen einer aktiven Anweisung zu. Wenn eine Anwendung SQLSetCursorName nicht aufruft, generiert der Treiber Cursornamen nach Bedarf für die SQL-Anweisungsverarbeitung.

Syntax

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

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

CursorName
[Eingabe] Cursorname. Zur effizienten Verarbeitung sollte der Cursorname keine führenden oder nachgestellten Leerzeichen im Cursornamen enthalten, und wenn der Cursorname einen durch Trennzeichen getrennten Bezeichner enthält, sollte das Trennzeichen als erstes Zeichen im Cursornamen positioniert werden.

NameLength
[Eingabe] Länge in Zeichen von *CursorName.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLSetCursorName SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLSetCursorName zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

Cursornamen werden nur in positionierten Aktualisierungs- und Löschanweisungen verwendet (z. B. UPDATE-Tabellenname ...WHERE CURRENT OF cursor-name). Weitere Informationen finden Sie unter Positioned Update and Delete-Anweisungen. Wenn die Anwendung SQLSetCursorName nicht aufruft, um einen Cursornamen zu definieren, generiert der Treiber bei ausführung einer Abfrageanweisung einen Namen, der mit den Buchstaben SQL_CUR beginnt und 18 Zeichen lang nicht überschreitet.

Alle Cursornamen innerhalb der Verbindung müssen eindeutig sein. Die maximale Länge eines Cursornamens wird vom Treiber definiert. Für die maximale Interoperabilität wird empfohlen, cursornamen auf maximal 18 Zeichen zu beschränken. In ODBC 3*.x*, wenn ein Cursorname ein Bezeichner mit Anmerkung ist, wird er auf groß-/kleinschreibungsbezogene Weise behandelt und kann Zeichen enthalten, die die Syntax von SQL nicht zulassen oder speziell behandeln würde, z. B. Leerzeichen oder reservierte Schlüsselwörter. Wenn ein Cursorname auf eine groß-/kleinschreibungsbezogene Weise behandelt werden muss, muss er als Anmerkungsbezeichner übergeben werden.

Ein Cursorname, der entweder explizit oder implizit festgelegt wird, bleibt so lange festgelegt, bis die Anweisung, der sie zugeordnet ist, mithilfe von SQLFreeHandle gelöscht wird. SQLSetCursorName kann aufgerufen werden, um einen Cursor in einer Anweisung umzubenennen, solange sich der Cursor in einem zugewiesenen oder vorbereiteten Zustand befindet.

Codebeispiel

Im folgenden Beispiel verwendet eine Anwendung SQLSetCursorName , um einen Cursornamen für eine Anweisung festzulegen. Anschließend wird diese Anweisung verwendet, um Ergebnisse aus der Tabelle CUSTOMERS abzurufen. Schließlich führt es eine positionierte Aktualisierung durch, um die Telefonnummer von John Smith zu ändern. Beachten Sie, dass die Anwendung unterschiedliche Anweisungshandles für die SELECT- und UPDATE-Anweisungen verwendet.

Ein weiteres Codebeispiel finden Sie unter 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);  
}  

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien