SQLSetCursorName-Funktion
Konformität
Version eingeführt: ODBC 1.0-Normenkonformität: 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 nachfolgenden Leerzeichen im Cursornamen enthalten, und wenn der Cursorname einen bezeichner mit Trennzeichen 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 wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLSetCursorName zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | Der Cursorname überschreitet den Höchstwert, sodass nur die maximal zulässige Anzahl von Zeichen verwendet wurde. |
| 24.000 | Ungültiger Cursorstatus | Die Anweisung, die StatementHandle entspricht, befand sich bereits in einem ausgeführten oder cursorpositionierten Zustand. |
| 34000 | Ungültiger Cursorname | Der in *CursorName angegebene Cursorname war ungültig, weil er die vom Treiber definierte maximale Länge überschritten hat, oder er begann mit "SQLCUR" oder "SQL_CUR". |
| 3C000 | Name des doppelten Cursors | Der in *CursorName angegebene Cursorname ist bereits vorhanden. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist. |
| HY009 | Ungültige Verwendung von NULL-Zeiger | (DM) Das Argument CursorName war ein NULL-Zeiger. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese aynchrone Funktion wurde noch ausgeführt, als die SQLSetCursorName-Funktion aufgerufen wurde. (DM) Eine asynchron ausführende Funktion wurde für das StatementHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die StatementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführung gesendet wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) Das Argument NameLength war kleiner als 0, aber nicht gleich SQL_NTS. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen 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 das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Der Treiber unterstützt diese Funktion nicht. | (DM) Der der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
Kommentare
Cursornamen werden nur in positionierten Update- und Löschanweisungen verwendet (z. B. UPDATE-Tabellenname ... WHERE CURRENT OFcursor-name). Weitere Informationen finden Sie unter Positionierte Update- und Delete-Anweisungen. Wenn die Anwendung SQLSetCursorName nicht aufruft, um einen Cursornamen zu definieren, generiert der Treiber bei der Ausführung einer Abfrageanweisung einen Namen, der mit den Buchstaben SQL_CUR beginnt und eine Länge von 18 Zeichen nicht überschreitet.
Alle Cursornamen innerhalb der Verbindung müssen eindeutig sein. Die maximale Länge eines Cursornamens wird vom Treiber definiert. Für eine maximale Interoperabilität wird empfohlen, dass Anwendungen Cursornamen auf nicht mehr als 18 Zeichen beschränken. Wenn ein Cursorname in ODBC 3*.x* ein Anführungszeichen ist, wird die Groß-/Kleinschreibung beachtet, und er 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 in einer Weise behandelt werden muss, bei der die Groß-/Kleinschreibung beachtet werden muss, muss er als Anführungszeichen übergeben werden.
Ein explizit oder implizit festgelegter Cursorname bleibt festgelegt, bis die Anweisung, der er zugeordnet ist, mithilfe von SQLFreeHandle gelöscht wird. SQLSetCursorName kann aufgerufen werden, um einen Cursor für eine Anweisung umzubenennen, solange sich der Cursor in einem zugeordneten 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 ein positioniertes Update aus, um die Telefonnummer von John Smith zu ändern. Beachten Sie, dass die Anwendung verschiedene 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
| 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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für