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.
| SQLSTATE | Error | Beschreibung |
|---|---|---|
| 01000 | Allgemeiner Warnhinweis | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | Der Cursorname hat den maximal zulässigen Grenzwert überschritten, sodass nur die maximal zulässige Anzahl von Zeichen verwendet wurde. |
| 24.000 | Ungültiger Cursorstatus | Die Anweisung, die "StatementHandle " entspricht, befindet sich 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 überschritten hat, wie vom Treiber definiert, oder er begann mit "SQLCUR" oder "SQL_CUR". |
| 3C000 | Doppelter Cursorname | 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 keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und dessen Ursache. |
| HY001 | Speicherzuweisungsfehler | Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen. |
| HY009 | Ungültige Verwendung des Nullzeigers | (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 aynchrone Funktion wurde noch ausgeführt, als die SQLSetCursorName-Funktion aufgerufen wurde. (DM) Eine asynchron ausgeführte Funktion wurde für " StatementHandle " aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für " StatementHandle " aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden. |
| HY013 | Speicherverwaltungsfehler | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen. |
| 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 des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt. |
| IM001 | Dieser Treiber unterstützt diese Funktion nicht. | (DM) Der dem StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
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 zu | Siehe |
|---|---|
| Ausführen einer SQL-Anweisung | SQLExecDirect-Funktion |
| Ausführen einer vorbereiteten SQL-Anweisung | SQLExecute-Funktion |
| Zurückgeben eines Cursornamens | SQLGetCursorName-Funktion |
| Festlegen von Bildlaufoptionen für den Cursor | SQLSetScrollOptions-Funktion |