Freigeben über

SQLGetStmtAttr-Funktion

  • Artikel

Konformität
Version eingeführt: ODBC 3.0-Normenkonformität: ISO 92

Zusammenfassung
SQLGetStmtAttr gibt die aktuelle Einstellung eines Anweisungsattributs zurück.

Hinweis

Weitere Informationen dazu, was der Treiber-Manager diese Funktion bei ODBC 3 ordnet. Die x-Anwendung arbeitet mit ODBC 2. x-Treiber , siehe Zuordnen von Ersatzfunktionen für die Abwärtskompatibilität von Anwendungen.

Syntax

  
SQLRETURN SQLGetStmtAttr(  
     SQLHSTMT        StatementHandle,  
     SQLINTEGER      Attribute,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Attribut
[Eingabe] Attribut, das abgerufen werden soll.

ValuePtr
[Ausgabe] Zeiger auf einen Puffer, in dem der Wert des in Attribut angegebenen Attributs zurückgegeben werden soll.

Wenn ValuePtr NULL ist, gibt StringLengthPtr weiterhin die Gesamtanzahl der Bytes (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den ValuePtr verweist.

BufferLength
[Eingabe] Wenn Attribut ein odbc-definiertes Attribut ist und ValuePtr auf eine Zeichenfolge oder einen binären Puffer verweist, sollte dieses Argument die Länge von *ValuePtr haben. Wenn Attribut ein ODBC-definiertes Attribut und *ValuePtr eine ganze Zahl ist, wird BufferLength ignoriert. Wenn der in *ValuePtr zurückgegebene Wert eine Unicode-Zeichenfolge ist (beim Aufrufen von SQLGetStmtAttrW), muss das BufferLength-Argument eine gerade Zahl sein.

Wenn Attribut ein vom Treiber definiertes Attribut ist, gibt die Anwendung die Art des Attributs für den Treiber-Manager an, indem das BufferLength-Argument festgelegt wird. BufferLength kann die folgenden Werte aufweisen:

  • Wenn *ValuePtr ein Zeiger auf eine Zeichenfolge ist, ist BufferLength die Länge der Zeichenfolge oder SQL_NTS.

  • Wenn *ValuePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des makros SQL_LEN_BINARY_ATTR(length) in BufferLength. Dadurch wird ein negativer Wert in BufferLength platziert.

  • Wenn *ValuePtr ein Zeiger auf einen anderen Wert als eine Zeichenfolge oder binäre Zeichenfolge ist, sollte BufferLength den Wert SQL_IS_POINTER haben.

  • Wenn *ValuePtr einen Datentyp mit fester Länge enthält, ist BufferLength entweder SQL_IS_INTEGER oder SQL_IS_UINTEGER.

StringLengthPtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem die Gesamtanzahl von Bytes (mit Ausnahme des NULL-Terminierungszeichens) zurückgegeben werden soll, die in *ValuePtr zurückgegeben werden können. Wenn der Attributwert eine Zeichenfolge ist und die Anzahl der zurückzugebenden Bytes größer oder gleich BufferLength ist, werden die Daten in *ValuePtr in BufferLength abgeschnitten, abzüglich der Länge eines NULL-Beendigungszeichens und vom Treiber null-beendet.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

Wenn SQLGetStmtAttr 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 SQLGetStmtAttr 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 Die in *ValuePtr zurückgegebenen Daten wurden als BufferLength abgeschnitten, abzüglich der Länge eines NULL-Terminierungszeichens. Die Länge des unwahren Zeichenfolgenwerts wird in *StringLengthPtr zurückgegeben. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
24.000 Ungültiger Cursorstatus Das Argument Attribut wurde SQL_ATTR_ROW_NUMBER und der Cursor war nicht geöffnet, oder der Cursor wurde vor dem Beginn des Resultsets oder nach dem Ende des Resultsets positioniert.
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 Argument MessageText 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.
HY010 Funktionssequenzfehler (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLGetStmtAttr-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) *ValuePtr ist eine Zeichenfolge, und BufferLength war kleiner als 00, aber nicht gleich SQL_NTS.
HY092 Ungültiger Attribut-/Optionsbezeichner Der für das Argument Attribut angegebene Wert war für die vom Treiber unterstützte ODBC-Version ungültig.
HY109 Ungültige Cursorposition Das Attributargument wurde SQL_ATTR_ROW_NUMBER, und die Zeile wurde gelöscht oder konnte nicht abgerufen werden.
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.
HYC00 Optionale Funktion nicht implementiert Der für das Argument Attribut angegebene Wert war ein gültiges ODBC-Anweisungsattribut für die vom Treiber unterstützte ODBC-Version, wurde aber vom Treiber nicht unterstützt.
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 Treiber, der dem StatementHandle entspricht, unterstützt die Funktion nicht.

Kommentare

Allgemeine Informationen zu Anweisungsattributen finden Sie unter Anweisungsattribute.

Ein Aufruf von SQLGetStmtAttr gibt in *ValuePtr den Wert des in Attribut angegebenen Anweisungsattributs zurück. Dieser Wert kann entweder ein SQLULEN-Wert oder eine NULL-Zeichenfolge sein. Wenn es sich bei dem Wert um einen SQLULEN-Wert handelt, schreiben einige Treiber möglicherweise nur den unteren 32-Bit- oder 16-Bit eines Puffers und lassen das Bit höherer Reihenfolge unverändert. Daher sollten Anwendungen einen Puffer von SQLULEN verwenden und den Wert auf 0 initialisieren, bevor diese Funktion aufgerufen wird. Außerdem werden die Argumente BufferLength und StringLengthPtr nicht verwendet. Wenn der Wert eine NULL-Zeichenfolge ist, gibt die Anwendung die maximale Länge dieser Zeichenfolge im BufferLength-Argument an, und der Treiber gibt die Länge dieser Zeichenfolge im Puffer *StringLengthPtr zurück.

Damit Anwendungen, die SQLGetStmtAttr aufrufen, mit ODBC 2 arbeiten können x-Treiber : Ein Aufruf von SQLGetStmtAttr wird im Treiber-Manager SQLGetStmtOption zugeordnet.

Die folgenden Anweisungsattribute sind schreibgeschützt, können daher von SQLGetStmtAttr abgerufen, aber nicht von SQLSetStmtAttr festgelegt werden:

  • SQL_ATTR_IMP_PARAM_DESC

  • SQL_ATTR_IMP_ROW_DESC

  • SQL_ATTR_ROW_NUMBER

Eine Liste der Attribute, die festgelegt und abgerufen werden können, finden Sie unter SQLSetStmtAttr.

Informationen über Finden Sie unter
Zurückgeben der Einstellung eines Verbindungsattributes SQLGetConnectAttr-Funktion
Festlegen eines Verbindungsattributes SQLSetConnectAttr-Funktion
Festlegen eines Anweisungsattributs SQLSetStmtAttr-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien