Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Tabellenwertparameter, wie andere Parameter, müssen gebunden werden, bevor sie an den Server übergeben werden. Die Anwendung bindet Tabellenwertparameter auf die gleiche Weise wie andere Parameter: mithilfe von SQLBindParameter oder entsprechenden Aufrufen von SQLSetDescField oder SQLSetDescRec. Der Serverdatentyp für einen Tabellenwertparameter ist SQL_SS_TABLE. Der C-Typ kann entweder als SQL_C_DEFAULT oder SQL_C_BINARY angegeben werden.
In SQL Server 2008 oder höher werden nur Eingabetabellenwertparameter unterstützt. Daher wird jeder Versuch, SQL_DESC_PARAMETER_TYPE auf einen anderen Wert als SQL_PARAM_INPUT festzulegen, SQL_ERROR mit SQLSTATE = HY105 und der Meldung "Ungültiger Parametertyp" zurückgegeben.
Mithilfe des Attributs SQL_CA_SS_COL_HAS_DEFAULT_VALUE können ganze Spalten mit Tabellenwertparametern Standardwerte zugewiesen werden. Einzelnen Spaltenwerten mit Tabellenwerten können jedoch keine Standardwerte zugewiesen werden, indem SQL_DEFAULT_PARAM in StrLen_or_IndPtr mit SQLBindParameter verwendet werden. Tabellenwertparameter als Ganzes können nicht auf einen Standardwert festgelegt werden, indem SQL_DEFAULT_PARAM in StrLen_or_IndPtr mit SQLBindParameter verwendet werden. Wenn diese Regeln nicht befolgt werden, gibt SQLExecute oder SQLExecDirect SQL_ERROR zurück. Ein Diagnosedatensatz wird mit SQLSTATE=07S01 und der Meldung "Ungültige Verwendung des Standardparameters für Parameter <p>" generiert, wobei <p> die Ordnungszahl des TVP in der Abfrageanweisung ist.
Nach der Bindung des Tabellenwertparameters muss die Anwendung dann jede Tabellenwertparameterspalte binden. Dazu ruft die Anwendung zuerst SQLSetStmtAttr auf, um SQL_SOPT_SS_PARAM_FOCUS auf die Ordnungszahl eines Tabellenwertparameters festzulegen. Anschließend bindet die Anwendung die Spalten des Tabellenwertparameters durch Aufrufe der folgenden Routinen: SQLBindParameter, SQLSetDescRec und SQLSetDescField. Durch festlegen SQL_SOPT_SS_PARAM_FOCUS auf 0 wird die übliche Wirkung von SQLBindParameter, SQLSetDescRec und SQLSetDescField bei der Ausführung normaler Parameter auf oberster Ebene wiederhergestellt.
Für den Tabellenwertparameter selbst werden keine tatsächlichen Daten gesendet oder empfangen, es werden jedoch Daten für jede einzelne Spalte gesendet und empfangen. Da der Parameter mit Tabellenwert eine Pseudospalte ist, werden die Parameter für SQLBindParameter verwendet, um auf unterschiedliche Attribute als andere Datentypen zu verweisen:
| Parameter | Verwandtes Attribut für Parametertypen ohne Tabellenwert, einschließlich Spalten | Verwandtes Attribut für Tabellenwertparameter |
|---|---|---|
| InputOutputType | SQL_DESC_PARAMETER_TYPE in IPD. Bei Spalten mit Tabellenwertparametern muss dies mit der Einstellung für den Tabellenwertparameter selbst identisch sein. |
SQL_DESC_PARAMETER_TYPE in IPD. Dies muss SQL_PARAM_INPUT sein. |
| ValueType | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE in APD. | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE in APD. Dies muss SQL_C_DEFAULT oder SQL_C_BINARY sein. |
| ParameterType | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE in IPD. | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE in IPD. Dies muss SQL_SS_TABLE werden. |
| ColumnSize | SQL_DESC_LENGTH oder SQL_DESC_PRECISION in IPD. Dies hängt vom Wert von ParameterType ab. |
SQL_DESC_ARRAY_SIZE Kann auch mithilfe von SQL_ATTR_PARAM_SET_SIZE festgelegt werden, wenn der Parameterfokus auf den parameterwertigen Parameter festgelegt ist. Bei einem Tabellenwertparameter ist dies die Anzahl der Zeilen in den Spaltenpuffern mit Tabellenwert. |
| Dezimaldigits | SQL_DESC_PRECISION oder SQL_DESC_SCALE in IPD. | Unbenutzt. Dies muss 0 sein. Wenn dieser Parameter nicht 0 ist, gibt SQLBindParameter SQL_ERROR zurück, und ein Diagnosedatensatz wird mit SQLSTATE= HY104 und der Meldung "Ungültige Genauigkeit oder Skalierung" generiert. |
| ParameterValuePtr | SQL_DESC_DATA_PTR in APD. | SQL_CA_SS_TYPE_NAME. Dies ist optional für Gespeicherte Prozeduraufrufe, und NULL kann angegeben werden, wenn sie nicht erforderlich ist. Es muss für SQL-Anweisungen angegeben werden, die keine Prozeduraufrufe sind. Dieser Parameter dient auch als eindeutiger Wert, den die Anwendung verwenden kann, um diesen Tabellenwertparameter zu identifizieren, wenn die Variable Zeilenbindung verwendet wird. Weitere Informationen finden Sie im Abschnitt "Variable Table-Valued Parameter Row Binding" weiter unten in diesem Thema. Wenn ein Tabellenwert-Parametertypname für einen Aufruf von SQLBindParameter angegeben wird, muss er als Unicode-Wert angegeben werden, auch in Anwendungen, die als ANSI-Anwendungen erstellt werden. Der für den Parameter verwendete Wert StrLen_or_IndPtr sollte entweder SQL_NTS oder die Zeichenfolgenlänge des namens multipliziert mit sizeof(WCHAR) sein. |
| BufferLength | SQL_DESC_OCTET_LENGTH in APD. | Die Länge des Tabellenwert-Parametertypnamens in Byte. Dies kann SQL_NTS werden, wenn der Typname null beendet ist, oder 0, wenn der Parametertypname mit Tabellenwert nicht erforderlich ist. |
| StrLen_or_IndPtr | SQL_DESC_OCTET_LENGTH_PTR in APD. | SQL_DESC_OCTET_LENGTH_PTR in APD. Bei Tabellenwertparametern ist dies eine Zeilenanzahl anstelle einer Datenlänge. |
Zwei Datenübertragungsmodi werden für Tabellenwertparameter unterstützt: feste Zeilenbindung und variable Zeilenbindung.
Table-Valued Parameterzeilenbindung wurde behoben
Bei fester Zeilenbindung weist eine Anwendung Puffer (oder Pufferarrays) für alle möglichen Eingabespaltenwerte groß genug zu. Die Anwendung führt folgende Aktionen aus:
Bindet alle Parameter mithilfe von SQLBindParameter-, SQLSetDescRec- oder SQLSetDescField-Aufrufen.
- Legt SQL_DESC_ARRAY_SIZE auf die maximale Anzahl von Zeilen fest, die für jeden Tabellenwertparameter übertragen werden können. Dies kann im SQLBindParameter-Aufruf erfolgen.
Ruft SQLSetStmtAttr auf, um SQL_SOPT_SS_PARAM_FOCUS auf die Ordnungszahl jedes Tabellenwertparameters festzulegen.
Binden Sie für jeden Parameter mit Tabellenwert mithilfe von SQLBindParameter-, SQLSetDescRec- oder SQLSetDescField-Aufrufen Tabellenwertparameterspalten.
Ruft für jede Tabellenwertparameterspalte, die Standardwerte enthalten soll, SQLSetDescField auf, um SQL_CA_SS_COL_HAS_DEFAULT_VALUE auf 1 festzulegen.
Ruft SQLSetStmtAttr auf, um SQL_SOPT_SS_PARAM_FOCUS auf 0 festzulegen. Dies muss erfolgen, bevor SQLExecute oder SQLExecDirect aufgerufen wird. Andernfalls wird SQL_ERROR zurückgegeben, und ein Diagnosedatensatz wird mit SQLSTATE=HY024 und der Meldung "Ungültiger Attributwert, SQL_SOPT_SS_PARAM_FOCUS (muss zur Ausführungszeit null sein)" generiert.
Legt fest, StrLen_or_IndPtr oder SQL_DESC_OCTET_LENGTH_PTR für einen Tabellenwertparameter ohne Zeilen SQL_DEFAULT_PARAM oder die Anzahl der Zeilen, die beim nächsten Aufruf von SQLExecute oder SQLExecDirect übertragen werden sollen, wenn der Parameter mit Tabellenwert Zeilen enthält. StrLen_or_IndPtr oder SQL_DESC_OCTET_LENGTH_PTR können für einen Tabellenwertparameter nicht auf SQL_NULL_DATA festgelegt werden, da tabellenwertige Parameter nicht nullwertefähig sind (obwohl tabellenwertige Parameterspalten nullwertefähig sein können). Wenn dies auf einen ungültigen Wert festgelegt ist, gibt SQLExecute oder SQLExecDirect SQL_ERROR zurück, und ein Diagnosedatensatz wird mit SQLSTATE=HY090 und der Meldung "Ungültige Zeichenfolge oder Pufferlänge für Parameter <p>" generiert, wobei p die Parameternummer ist.
Ruft SQLExecute oder SQLExecDirect auf.
Spaltenwerte für eingabetabellenwertige Parameter können in Teilen übergeben werden, wenn StrLen_or_IndPtr auf SQL_LEN_DATA_AT_EXEC(Länge) oder SQL_DATA_AT_EXEC für die Spalte festgelegt ist. Dies ähnelt dem Übergeben von Werten in Teilen, wenn Arrays von Parametern verwendet werden. Wie bei allen Daten-at-Execution-Parametern gibt SQLParamData nicht an, für welche Zeile des Arrays der Treiber Daten anfordert; der Antrag muss sich darum kümmern. Die Anwendung kann keine Annahmen über die Reihenfolge machen, in der der Treiber Werte anfordert.
Variable Table-Valued Parameterzeilenbindung
Bei variabler Zeilenbindung werden Zeilen zur Ausführungszeit in Batches übertragen, und die Anwendung übergibt Zeilen bei Bedarf an den Treiber. Dies ähnelt der Datenausführung für einzelne Parameterwerte. Für die Bindung variabler Zeilen führt die Anwendung folgende Aktionen aus:
Bindet Parameter und Spalten mit Tabellenwerten, wie in den Schritten 1 bis 3 des vorherigen Abschnitts "Feste Table-Valued Parameterzeilenbindung" beschrieben.
Legt StrLen_or_IndPtr oder SQL_DESC_OCTET_LENGTH_PTR für alle Parameter mit Tabellenwerten fest, die zur Ausführungszeit an SQL_DATA_AT_EXEC übergeben werden sollen. Wenn keines festgelegt ist, wird der Parameter wie im vorherigen Abschnitt beschrieben verarbeitet.
Ruft SQLExecute oder SQLExecDirect auf. Dies gibt SQL_NEED_DATA zurück, wenn SQL_PARAM_INPUT oder SQL_PARAM_INPUT_OUTPUT Parameter als Daten-at-Execution-Parameter behandelt werden sollen. In diesem Fall führt die Anwendung folgende Aktionen aus:
- Ruft SQLParamData auf. Dadurch wird der ParameterValuePtr-Wert für einen Data-at-Execution-Parameter und einen Rückgabecode von SQL_NEED_DATA zurückgegeben. Wenn alle Parameterdaten an den Treiber übergeben wurden, gibt SQLParamData SQL_SUCCESS, SQL_SUCCESS_WITH_INFO oder SQL_ERROR zurück. Bei Daten-at-Execution-Parametern kann ParameterValuePtr, der mit dem Deskriptorfeld SQL_DESC_DATA_PTR identisch ist, als Token betrachtet werden, um einen Parameter eindeutig zu identifizieren, für den ein Wert erforderlich ist. Dieses "Token" wird zur Bindungszeit von der Anwendung an den Treiber übergeben und dann zur Ausführungszeit an die Anwendung übergeben.
Zum Senden von Tabellenwert-Parameterzeilendaten für Null-Tabellenwertparameter ruft eine Anwendung SQLPutData mit StrLen_or_Ind auf SQL_DEFAULT_PARAM fest, wenn der Parameter mit Tabellenwert keine Zeilen enthält.
Für Nicht-NULL-TVPs:
Legt Str_Len_or_Ind für alle Tabellenwertparameterspalten auf geeignete Werte fest und füllt Datenpuffer für Spalten mit Tabellenwertparametern auf, die keine Daten bei ausführungsparametern sind. Sie können daten-at-execution für Tabellenwertparameterspalten auf eine ähnliche Weise verwenden wie die, in der normale Parameter an den Treiber in Teilen übergeben werden können.
Ruft SQLPutData auf, wobei Str_Len_or_Ind auf die Anzahl der Zeilen festgelegt ist, die an den Server gesendet werden sollen. Jeder Wert außerhalb des Bereichs 0 bis SQL_DESC_ARRAY_SIZE oder SQL_DEFAULT_PARAM ist ein Fehler und gibt SQLSTATE HY090 mit der Meldung "Ungültige Zeichenfolge oder Pufferlänge" zurück. 0 gibt an, dass alle Zeilen gesendet wurden und es keine weiteren Daten für einen Tabellenwertparameter gibt (wie im zweiten Aufzählungszeichen in dieser Liste angegeben). SQL_DEFAULT_PARAM kann nur verwendet werden, wenn der Treiber zum ersten Mal Daten für einen Tabellenwertparameter anfordert (wie im ersten Aufzählungselement in dieser Liste beschrieben).
Wenn alle Zeilen gesendet wurden, ruft SQLPutData für den Tabellenwertparameter mit einem Str_Len_or_Ind Wert von 0 auf, und fahren Sie dann mit Schritt 3a oben fort.
Ruft SQLParamData erneut auf. Wenn in den Spalten mit tabellenwertigen Parametern Daten zur Ausführung vorhanden sind, werden diese durch den Wert ValuePtrPtrPtr identifiziert, der von SQLParamData zurückgegeben wird. Wenn alle Spaltenwerte verfügbar sind, gibt SQLParamData erneut den ParameterValuePtr-Wert für den Parameter "table-valued" zurück, und die Anwendung beginnt erneut.