SQLDescribeParam
Zur Beschreibung der Parameter einer SQL-Anweisung erstellt der SQL Server Native Client ODBC-Treiber eine Transact-SQL SELECT-Anweisung und führt diese aus, wenn SQLDescribeParam für ein vorbereitetes ODBC-Anweisungshandle aufgerufen wird. Beim Ausführen der Abfrage verwendet der Treiber die SET FMTONLY-Anweisung. Die Metadaten des Resultsets bestimmen die Eigenschaften der Parameter in der vorbereiteten Anweisung.
Angenommen, die folgende ODBC SQL-Anweisung wird ausgeführt:
INSERT INTO Shippers (ShipperID, CompanyName, Phone) VALUES (?, ?, ?)
Bei einem Aufruf von SQLDescribeParam veranlasst diese ODBC SQL-Anweisung den Treiber, die folgenden Transact-SQL-Anweisungen auszuführen:
SET FMTONLY ON
SELECT ShipperID, CompanyName, Phone FROM Shippers
SET FMTONLY OFF
SQLDescribeParam kann deshalb jeden Fehlercode zurückgeben, den SQLExecute oder SQLExecDirect zurückgeben könnte.
Des Weiteren unterstützt der Treiber das Aufrufen von SQLDescribeParam in folgenden Situationen nicht:
Nach SQLExecDirect für eine Transact-SQL-UPDATE- oder DELETE-Anweisung, die die FROM-Klausel enthält.
Für eine ODBC- oder Transact-SQL-Anweisung, die einen Parameter in einer HAVING-Klausel enthält oder die mit dem Ergebnis einer SUM-Funktion verglichen wird.
Für eine ODBC- oder Transact-SQL-Anweisung abhängig von einer Unterabfrage, die Parameter enthält.
Für ODBC SQL-Anweisungen, die Parametermarkierungen in beiden Ausdrücken eines Vergleichs oder quantifizierten Prädikats enthalten.
Für Abfragen, bei denen einer der Parameter ein Parameter für eine Funktion ist.
Wenn der Transact-SQL-Befehl Kommentare (/* */) beinhaltet.
Bei der Verarbeitung von Batches mit Transact-SQL-Anweisungen unterstützt der Treiber außerdem für Parametermarker in Anweisungen nach der ersten Anweisung im Batch keine Aufrufe von SQLDescribeParam.
Beim Beschreiben der Parameter von vorbereiteten gespeicherten Prozeduren verwendet SQLDescribeParam die gespeicherte Systemprozedur sp_sproc_columns zum Abrufen von Parametereigenschaften. sp_sproc_columns kann Daten für gespeicherte Prozeduren innerhalb der aktuellen Benutzerdatenbank melden. Durch Vorbereiten eines vollqualifizierten Namens für die gespeicherte Prozedur kann SQLDescribeParam über Datenbanken hinweg ausgeführt werden. Die gespeicherte Systemprozedur sp_who kann in jeder Datenbank wie folgt vorbereitet und ausgeführt werden:
SQLPrepare(hstmt, "{call sp_who(?)}", SQL_NTS);
Durch Ausführen von SQLDescribeParam nach erfolgreicher Vorbereitung wird ein leeres Rowset zurückgegeben, wenn eine Verbindung zu einer Datenbank mit Ausnahme der master-Datenbank besteht. Der gleiche Aufruf bewirkt, dass SQLDescribeParam unabhängig von der aktuellen Benutzerdatenbank erfolgreich ist. Der Aufruf muss dazu wie folgt vorbereitet sein:
SQLPrepare(hstmt, "{call master..sp_who(?)}", SQL_NTS);
Für Datentypen mit umfangreichen Werten ist der in DataTypePtr zurückgegebene Wert SQL_VARCHAR, SQL_VARBINARY oder SQL_NVARCHAR. Um anzugeben, dass die Größe des Datentypparameters für umfangreiche Werte "unbegrenzt" ist, legt der SQL Server Native Client ODBC-Treiber ParameterSizePtr auf 0 fest. Tatsächliche Größenwerte werden für varchar-Standardparameter zurückgegeben.
.gif "Hinweis") Hinweis |
|---|
Wenn der Parameter bereits mit einer Maximalgröße für den SQL_VARCHAR-, SQL_VARBINARY- oder SQL_WVARCHAR-Parameter gebunden wurde, wird die gebundene Größe des Parameters und nicht "unbegrenzt" zurückgegeben. |
Um einen Eingabeparameter mit "unbegrenzter" Größe zu binden, muss Data-at-Execution verwendet werden. Es ist nicht möglich, einen Ausgabeparameter mit "unbegrenzter" Größe zu binden (es gibt keine Möglichkeit für das Streaming von Daten von einem Ausgabeparameter, wie SQLGetData es beispielsweise für Resultsets ermöglicht).
Für Ausgabeparameter muss ein Puffer gebunden werden und wenn der Wert zu umfangreich ist, wird der Puffer aufgefüllt und eine SQL_SUCCESS_WITH_INFO-Meldung wird zusammen mit einer Warnung "Zeichenfolgendaten werden rechts abgeschnitten" zurückgegeben. Die abgeschnittenen Daten werden anschließend verworfen.
SQLDescribeParam und Tabellenwertparameter
Eine Anwendung kann Informationen über Tabellenwertparameter für eine vorbereitete Anweisung mit SQLDescribeParam abrufen. Weitere Informationen finden Sie unter Tabellenwertparameter-Metadaten für vorbereitete Anweisungen.
Weitere Informationen zu Tabellenwertparametern im Allgemeinen finden Sie unter Tabellenwertparameter (ODBC).
SQLDescribeParam-Unterstützung für erweiterte Features für Datum und Uhrzeit
Die für Datums-/Uhrzeittypen zurückgegebenen Werte lauten wie folgt:
DataTypePtr |
ParameterSizePtr |
DecimalDigitsPtr |
|
|---|---|---|---|
datetime |
SQL_TYPE_TIMESTAMP |
23 |
3 |
smalldatetime |
SQL_TYPE_TIMESTAMP |
16 |
0 |
date |
SQL_TYPE_DATE |
10 |
0 |
time |
SQL_SS_TIME2 |
8, 10..16 |
0..7 |
datetime2 |
SQL_TYPE_TIMESTAMP |
19, 21..27 |
0..7 |
datetimeoffset |
SQL_SS_TIMESTAMPOFFSET |
26, 28..34 |
0..7 |
Weitere Informationen finden Sie unter Datums-/Uhrzeitverbesserungen (ODBC).
SQLDescribeParam-Unterstützung für große CLR-UDTs
SQLDescribeParam unterstützt große benutzerdefinierte CLR-Typen (UDTs). Weitere Informationen finden Sie unter Große benutzerdefinierte CLR-Typen (ODBC).