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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien