SQLSetCursorName-Funktion

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

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

Syntax

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

Argumente

AnweisungHandle
[Eingabe] Anweisungshandpunkt.

CursorName
[Eingabe] Cursorname. Bei der effizienten Verarbeitung sollte der Cursorname keine führenden oder nachgestellten Leerzeichen im Cursornamen enthalten, und wenn der Cursorname einen 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.

Diagnose

Wenn SQLSetCursorName SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle aufgerufen werden. In der folgenden Tabelle sind die VON SQLSetCursorName zurückgegebenen SQLSetCursorName-Werte aufgeführt und werden im Kontext dieser Funktion erläutert; die Notation "(DM)" vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der zurückgegebene Code, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

SQLSTATE Fehler Beschreibung
01000 Allgemeine Warnung Treiberspezifische Informationsnachricht. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01004 Zeichenfolgendaten, rechts abgeschnitten Der Cursorname überschreitet den maximal zulässigen Grenzwert, sodass nur die maximale zulässige Anzahl von Zeichen verwendet wurde.
24.000 Ungültiger Cursorstatus Die Anweisung, die dem StatementHandle entspricht, war bereits in einem ausgeführten oder Cursorpositionierten Zustand.
34000 Ungültiger Cursorname Der in *CursorName angegebene Cursorname war ungültig, da er die maximale Länge überschreitet, wie von dem Treiber definiert, oder er begann mit "SQLCUR" oder "SQL_CUR".
3C000 Duplizieren des Cursornamens Der in *CursorName angegebene Cursorname ist bereits vorhanden.
HY000 Allgemeiner Fehler Ein Fehler, für den es keine spezifische SQLSTATE gab und für die keine implementierungsspezifische SQLSTATE definiert wurde. Die fehlermeldung, die von SQLGetDiagRec im *MessageText-Puffer zurückgegeben wird, beschreibt den Fehler und die Ursache.
HY001 Fehler bei der Speicherzuweisung Der Treiber konnte den Arbeitsspeicher nicht zuweisen, der für die Ausführung oder Den Abschluss der Funktion erforderlich ist.
HY009 Ungültige Verwendung von Nullzeigern (DM) Das Argument CursorName war ein Nullzeiger.
HY010 Funktionssequenzfehler (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese aynchronische Funktion wurde noch ausgeführt, als die SQLSetCursorName-Funktion aufgerufen wurde.

(DM) Eine asynchron ausgeführte Funktion wurde für die AnweisungHandle aufgerufen und wurde weiterhin ausgeführt, wenn diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die AnweisungHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Datenausführungsparameter oder Spalten gesendet wurden.
HY013 Fehler bei der Speicherverwaltung Der Funktionsaufruf konnte nicht verarbeitet werden, da die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnten, möglicherweise aufgrund niedriger Speicherbedingungen.
HY090 Ungültige Zeichenfolge oder Pufferlänge (DM) Das Argument NameLength war kleiner als 0, aber nicht gleich SQL_NTS.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Nur Trenn- und Schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für die Verbindung ist abgelaufen, bevor die Datenquelle auf die Anforderung reagierte. Der Zeitoutzeitraum für die Verbindung wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001 Treiber unterstützt diese Funktion nicht. (DM) Der mit der AnweisungHandle verknüpfte Treiber unterstützt die Funktion nicht.

Kommentare

Cursornamen werden nur in positionierten Update- und Delete-Anweisungen verwendet (z. B. UPDATEtable-Name ... WHERE CURRENTOFcursor-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 einen Namen, der mit den Buchstaben SQL_CUR beginnt und nicht mehr als 18 Zeichen lang ist.

Alle Cursornamen innerhalb der Verbindung müssen eindeutig sein. Die maximale Länge eines Cursornamens wird durch den Treiber definiert. Für maximale Interoperabilität wird empfohlen, dass Anwendungen Cursornamen auf nicht mehr als 18 Zeichen beschränken. Bei ODBC 3*.x*, wenn ein Cursorname ein angehaltener Bezeichner ist, wird er auf groß-bezogene 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ß-/Kleinschreibung behandelt werden muss, muss er als angestellter Bezeichner übergeben werden.

Ein Cursorname, der entweder explizit oder implizit festgelegt wird, bleibt festgelegt, bis die Anweisung, mit der sie verknüpft ist, mit SQLFreeHandle abgelegt wird. SQLSetCursorName kann aufgerufen werden, um einen Cursor in einer Anweisung umzubenennen, solange der Cursor sich 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 "KUNDEN" abzurufen. Schließlich führt es ein positioniertes Update aus, um die Telefonnummer von John Smith zu ändern. Beachten Sie, dass die Anwendung unterschiedliche Anweisungshandpunkte 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);  
}  
Informationen über Finden Sie unter
Ausführen einer SQL-Anweisung SQLExecDirect-Funktion
Ausführen einer vorbereiteten SQL-Anweisung SQLExecute-Funktion
Zurückgeben eines Cursornamens SQLGetCursorName-Funktion
Festlegen von Cursorlaufoptionen SQLSetScrollOptions-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien