SQLGetStmtAttr-Funktion

Konformität
Eingeführte Version: ODBC 3.0 Normenkonformität: ISO 92

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

Syntax

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

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Attribut
[Eingabe] Attribut zum Abrufen.

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

Wenn ValuePtr NULL ist, gibt StringLengthPtr weiterhin die Gesamtzahl der Bytes zurück (ohne das Null-Terminationszeichen für Zeichendaten), die im von ValuePtr gezeigten Puffer zurückgegeben werden können.

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

Wenn Attribute ein treiberdefiniertes Attribut ist, teilt die Anwendung die Natur des Attributs dem Driver Manager an, indem sie das BufferLength-Argument setzt. BufferLength kann folgende Werte haben:

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

• Wenn *ValuePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des Makros SQL_LEN_BINARY_ATTR(Länge) in BufferLength. Dies setzt einen negativen Wert in BufferLength.

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

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

StringLengthPtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem die Gesamtzahl der Bytes (ohne das Null-Terminationszeichen) zurückgegeben werden kann, die in *ValuePtr zurückgegeben werden können. Wenn der Attributwert eine Zeichenfolge ist und die Anzahl der verfügbaren Bytes größer oder gleich BufferLength ist, werden die Daten in *ValuePtr auf BufferLength minus die Länge eines Null-Terminations-Zeichens gekürzt und vom Treiber null-terminiert.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLGetStmtAttr SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert erhalten werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von StatementHandle aufgerufen wird. Die folgende Tabelle listet die SQLSTATE-Werte auf, die häufig von SQLGetStmtAttr zurückgegeben werden, und erklärt jeden einzelnen im Kontext dieser Funktion; die Notation "(DM)" geht den vom Treibermanager zurückgegebenen SQLSTATE-Beschreibungen voraus. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

Allgemeine Informationen zu Aussagenattributen finden Sie unter Aussagenattribute.

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-terminierte Zeichenfolge sein. Wenn der Wert ein SQLULEN-Wert ist, schreiben manche Treiber möglicherweise nur die unteren 32-Bit- oder 16-Bit-Teile eines Puffers und lassen das höherwertige Bit unverändert. Daher sollten Anwendungen einen SQLULEN-Puffer verwenden und den Wert vor dem Aufruf dieser Funktion auf 0 initialisieren. Außerdem werden die Argumente BufferLength und StringLengthPTR nicht verwendet. Ist der Wert ein null-terminierter String, gibt die Anwendung im BufferLength-Argument die maximale Länge dieses Strings an, und der Treiber gibt die Länge dieses Strings im *StringLengthPtr-Puffer zurück.

Um Anwendungen mit SQLGetStmtAttr mit ODBC 2 arbeiten zu lassen. x-Treiber wird ein Aufruf zu SQLGetStmtAttr im Driver Manager SQLGetStmtOption zugeordnet.

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

• SQL_ATTR_IMP_PARAM_DESC

• SQL_ATTR_IMP_ROW_DESC

• SQL_ATTR_ROW_NUMBER

Eine Liste von Attributen, die gesetzt und abgerufen werden können, finden Sie unter SQLSetStmtAttr.

Verwandte Funktionen

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien