Freigeben über


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.
24000 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);  
}  
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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien