SQLGetCursorName-Funktion
Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92
Zusammenfassung
SQLGetCursorName gibt den Cursornamen zurück, der einer angegebenen Anweisung zugeordnet ist.
Syntax
SQLRETURN SQLGetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr);
Argumente
StatementHandle
[Eingabe] Anweisungshandle.
CursorName
[Ausgabe] Zeigen Sie auf einen Puffer, in dem der Cursorname zurückgegeben werden soll.
Wenn CursorName NULL ist, gibt NameLengthPtr weiterhin die Gesamtzahl der Zeichen zurück (mit Ausnahme des Nullendpunkts für Zeichendaten), die im Puffer zurückgegeben werden können, auf den CursorName verweist.
BufferLength
[Eingabe] Länge von *CursorName in Zeichen.
NameLengthPtr
[Ausgabe] Zeigen Sie auf den Arbeitsspeicher, in dem die Gesamtanzahl der Zeichen (mit Ausnahme des Nullendpunkts) zurückgegeben werden soll, die in *CursorName zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer oder gleich "BufferLength" ist, wird der Cursorname in "*CursorName" auf "BufferLength" abgeschnitten, minus der Länge eines Null-Beendigungszeichens.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnostik
Wenn SQLGetCursorName entweder 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 SQLGetCursorName 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 Puffer *CursorName war nicht groß genug, um den gesamten Cursornamen zurückzugeben, sodass der Cursorname abgeschnitten wurde. Die Länge des nicht eindeutigen Cursornamens wird in *NameLengthPtr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 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. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLGetCursorName-Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für " StatementHandle " aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. (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. |
| HY015 | Kein Cursorname verfügbar | (DM) Der Treiber war ein ODBC 2*.x*-Treiber, es gab keinen geöffneten Cursor für die Anweisung, und es wurde kein Cursorname mit SQLSetCursorName festgelegt. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) Der im Argument BufferLength angegebene Wert war kleiner als 0. |
| 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 einen Namen. Dieser Name beginnt mit den Buchstaben SQL_CUR.
Hinweis
In ODBC 2*.x*, wenn kein geöffneter Cursor vorhanden war und kein Name durch einen Aufruf von SQLSetCursorName festgelegt wurde, hat ein Aufruf von SQLGetCursorName SQLSTATE HY015 zurückgegeben (kein Cursorname verfügbar). In ODBC 3*.x* ist dies nicht mehr wahr; Unabhängig davon, wann SQLGetCursorName aufgerufen wird, gibt der Treiber den Cursornamen zurück.
SQLGetCursorName gibt den Namen eines Cursors zurück, unabhängig davon, ob der Name explizit oder implizit erstellt wurde. Ein Cursorname wird implizit generiert, wenn SQLSetCursorName nicht aufgerufen wird. SQLSetCursorName kann aufgerufen werden, um einen Cursor in einer Anweisung umzubenennen, solange sich der Cursor in einem zugewiesenen oder vorbereiteten Zustand befindet.
Ein Cursorname, der entweder explizit oder implizit festgelegt wird, bleibt so lange festgelegt, bis das StatementHandle , dem es zugeordnet ist, mit SQLFreeHandle mit einem HandleType von SQL_HANDLE_STMT abgelegt wird.
Verwandte Funktionen
| Weitere Informationen zu | Siehe |
|---|---|
| Ausführen einer SQL-Anweisung | SQLExecDirect-Funktion |
| Ausführen einer vorbereiteten SQL-Anweisung | SQLExecute-Funktion |
| Vorbereiten einer Anweisung für die Ausführung | SQLPrepare-Funktion |
| Festlegen eines Cursornamens | SQLSetCursorName-Funktion |