Große benutzerdefinierte CLR-Typen (ODBC)
Gilt für: 
SQL Server Azure SQL-Datenbank Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)
Wichtig
SQL Server Native Client (SNAC) wird nicht ausgeliefert mit:
- SQL Server 2022 (16.x) und höhere Versionen
- SQL Server Management Studio 19 und spätere Versionen
Der SQL Server Native Client (SQLNCLI oder SQLNCLI11) und der Microsoft OLE DB-Legacyanbieter für SQL Server (SQLOLEDB) werden für neue Anwendungsentwicklungen nicht empfohlen.
Für neue Projekte verwenden Sie einen der folgenden Treiber:
Informationen zu SQLNCLI, das als Komponente der SQL Server-Datenbank-Engine (Versionen 2012 bis 2019) verfügbar ist, finden Sie in dieser Ausnahme für den Supportlebenszyklus.
In diesem Abschnitt werden Änderungen an ODBC in SQL Server Native Client erläutert, durch die große benutzerdefinierte Common Language Runtime-Typen (CLR-UDTs) unterstützt werden.
Ein Beispiel zur ODBC-Unterstützung für große CLR-UDTs finden Sie unter "Unterstützung für große UDTs".
Weitere Informationen zur Unterstützung großer CLR-UDTs in SQL Server Native Client finden Sie unter Large CLR User-Defined Types.For more information about support for large CLR UDTs in SQL Server Native Client, see Large CLR User-Defined Types.
Datenformat
SQL Server Native Client verwendet SQL_SS_LENGTH_UNLIMITED, um anzugeben, dass die Größe einer Spalte 8.000 Bytes für LOB-Typen (Large Object) überschreitet. Ab SQL Server 2008 wird derselbe Wert für CLR-UDTs mit einer Größe von über 8.000 Bytes verwendet.
UDT-Werte werden als Bytearrays dargestellt. Konvertierungen zu und von hexadezimalen Zeichenfolgen werden unterstützt. Literalwerte werden mit dem Präfix 0x als hexadezimale Zeichenfolgen dargestellt.
In der folgenden Tabelle wird die Datentypzuordnung in Parametern und Resultsets gezeigt:
| SQL Server-Datentyp | SQL-Datentyp | Wert |
|---|---|---|
| CLR-UDT | SQL_SS_UDT | -151 (sqlncli.h) |
In der folgenden Tabelle werden die entsprechenden Strukturen und ODBC C-Typen erläutert. Im Wesentlichen ist CLR UDT ein varbinärer Typ mit zusätzlichen Metadaten.
| SQL-Datentyp | Speicherlayout | C-Datentyp | Wert (sqlext.h) |
|---|---|---|---|
| SQL_SS_UDT | SQLCHAR *(nicht signiertes Zeichen *) | SQL_C_BINARY | SQL_BINARY (-2) |
Deskriptorfelder für Parameter
In den IPD-Feldern werden Informationen wie folgt zurückgegeben:
| Deskriptorfeld | SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT (Länge größer als 8.000 Bytes) |
|---|---|---|
| SQL_DESC_CASE_SENSITIVE | SQL_FALSE | SQL_FALSE |
| SQL_DESC_CONCISE_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| SQL_DESC_DATETIME_INTERVAL_CODE | 0 | 0 |
| SQL_DESC_DATETIME_INTERVAL_PRECISION | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_FIXED_PREC_SCALE | SQL_FALSE | SQL_FALSE |
| SQL_DESC_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_LOCAL_TYPE_NAME | "udt" | "udt" |
| SQL_DESC_OCTET_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_PRECISION | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_SCALE | 0 | 0 |
| SQL_DESC_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| SQL_DESC_TYPE_NAME | "udt" | "udt" |
| SQL_DESC_UNSIGNED | SQL_TRUE | SQL_TRUE |
| SQL_CA_SS_UDT_CATALOG_NAME | Der Name des Katalogs, der die UDT enthält. | Der Name des Katalogs, der die UDT enthält. |
| SQL_CA_SS_UDT_SCHEMA_NAME | Der Name des Schemas, das den UDT enthält. | Der Name des Schemas, das das UDT enthält. |
| SQL_CA_SS_UDT_TYPE_NAME | Dies ist der Name des UDT. | Dies ist der Name des UDT. |
| SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME | Der vollqualifizierte Name des UDT. | Der vollqualifizierte Name des UDT. |
Für UDT-Parameter muss SQL_CA_SS_UDT_TYPE_NAME immer über SQLSetDescField festgelegt werden. SQL_CA_SS_UDT_CATALOG_NAME und SQL_CA_SS_UDT_SCHEMA_NAME sind optional.
Ist der UDT in derselben Datenbank mit einem anderen Schema als die Tabelle definiert, muss SQL_CA_SS_UDT_SCHEMA_NAME festgelegt werden.
Ist der UDT in einer anderen Datenbank als die Tabelle definiert, müssen SQL_CA_SS_UDT_CATALOG_NAME und SQL_CA_SS_UDT_SCHEMA_NAME festgelegt werden.
Bei Fehlern oder Auslassungen in den Einstellungen für SQL_CA_SS_UDT_TYPE_NAME, SQL_CA_SS_UDT_CATALOG_NAME oder SQL_CA_SS_UDT_SCHEMA_NAME wird ein Diagnosedatensatz mit SQLSTATE HY000 und einem serverspezifischen Meldungstext generiert.
Deskriptorfelder für Ergebnisse
In den IRD-Feldern werden Informationen wie folgt zurückgegeben:
| Deskriptorfeld | SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT (Länge größer als 8.000 Bytes) |
|---|---|---|
| SQL_DESC_AUTO_UNIQUE_VALUE | SQL_FALSE | SQL_FALSE |
| SQL_DESC_CASE_SENSITIVE | SQL_FALSE | SQL_FALSE |
| SQL_DESC_CONCISE_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| SQL_DESC_DATETIME_INTERVAL_CODE | 0 | 0 |
| SQL_DESC_DATETIME_INTERVAL_PRECISION | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_DISPLAY_SIZE | 2n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_FIXED_PREC_SCALE | SQL_FALSE | SQL_FALSE |
| SQL_DESC_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_LITERAL_PREFIX | "0x" | "0x" |
| SQL_DESC_LITERAL_SUFFIX | "" | "" |
| SQL_DESC_LOCAL_TYPE_NAME | "udt" | "udt" |
| SQL_DESC_OCTET_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_PRECISION | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SQL_DESC_SCALE | 0 | 0 |
| SQL_DESC_SEARCHABLE | SQL_PRED_NONE | SQL_PRED_NONE |
| SQL_DESC_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| SQL_DESC_TYPE_NAME | "udt" | "udt" |
| SQL_DESC_UNSIGNED | SQL_TRUE | SQL_TRUE |
| SQL_CA_SS_UDT_CATALOG_NAME | Der Name des Katalogs, der die UDT enthält. | Der Name des Katalogs, der die UDT enthält. |
| SQL_CA_SS_UDT_SCHEMA_NAME | Der Name des Schemas, das den UDT enthält. | Der Name des Schemas, das den UDT enthält. |
| SQL_CA_SS_UDT_TYPE_NAME | Dies ist der Name des UDT. | Dies ist der Name des UDT. |
| SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME | Der vollqualifizierte Name des UDT. | Der vollqualifizierte Name des UDT. |
Von SQLColumns und SQLProcedureColumns zurückgegebene Spaltenmetadaten (Katalogmetadaten)
Die folgenden Spaltenwerte werden für UDTs zurückgegeben:
| Spaltenname | SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT (Länge größer als 8.000 Bytes) |
|---|---|---|
| DATA_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| TYPE_NAME | Dies ist der Name des UDT. | Dies ist der Name des UDT. |
| COLUMN_SIZE | n | SQL_SS_LENGTH_UNLIMITED (0) |
| BUFFER_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| DECIMAL_DIGITS | NULL | NULL |
| SQL_DATA_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| SQL_DATETIME_SUB | NULL | NULL |
| CHAR_OCTET_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SS_UDT_CATALOG_NAME | Der Name des Katalogs, der die UDT enthält. | Der Name des Katalogs, der die UDT enthält. |
| SS_UDT_SCHEMA_NAME | Der Name des Schemas, das den UDT enthält. | Der Name des Schemas, das den UDT enthält. |
| SS_UDT_ASSEMBLY_TYPE_NAME | Der vollqualifizierte Name des UDT. | Der vollqualifizierte Name des UDT. |
Die letzten drei Spalten sind treiberspezifische Spalten. Sie werden nach allen ODBC-definierten Spalten hinzugefügt, aber vor vorhandenen treiberspezifischen Spalten des Resultsets von SQLColumns oder SQLProcedureColumns.
Für einzelne UDTs oder für den generischen Typ "udt" werden keine Zeilen von SQLGetTypeInfo zurückgegeben.
Bindungen und Konvertierungen
Die unterstützten Konvertierungen von SQL- zu C-Datentypen sind wie folgt:
| Konvertierung von und zu: | SQL_SS_UDT |
|---|---|
| SQL_C_WCHAR | Unterstützt* |
| SQL_C_BINARY | Unterstützt |
| SQL_C_CHAR | Unterstützt* |
* Binäre Daten werden in eine Hexzeichenfolge konvertiert.
Die unterstützten Konvertierungen von C- zu SQL-Datentypen sind wie folgt:
| Konvertierung von und zu: | SQL_SS_UDT |
|---|---|
| SQL_C_WCHAR | Unterstützt* |
| SQL_C_BINARY | Unterstützt |
| SQL_C_CHAR | Unterstützt* |
* Hex-Zeichenfolge in binäre Datenkonvertierung erfolgt.
SQL_VARIANT-Unterstützung für UDTs
UDTs werden in SQL_VARIANT-Spalten nicht unterstützt.
BCP-Unterstützung für UDTs
UDT-Werte können nur als Zeichen oder Binärwerte importiert und exportiert werden.
Verhalten von Clients der unteren Ebene für UDTs
Für UDTs gilt die folgende Typzuordnung zu Clients der unteren Ebene:
| Serverversion | SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT (Länge größer als 8.000 Bytes) |
|---|---|---|
| SQL Server 2005 | UDT | varbinary(max) |
| SQL Server 2008 und höher | UDT | UDT |
ODBC-Funktionen, die große CLR-UDTs unterstützen
In diesem Abschnitt werden Änderungen an SQL Server Native Client-ODBC-Funktionen erläutert, durch die große CLR-UDTs unterstützt werden.
SQLBindCol
UDT-Ergebnisspaltenwerte werden von SQL in C-Datentypen konvertiert, wie im Abschnitt "Bindungen und Konvertierungen" weiter oben in diesem Thema beschrieben.
SQLBindParameter
Für UDTs sind folgende Werte erforderlich:
| SQL-Datentyp | Parametertyp | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (Länge größer als 8.000 Bytes) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLColAttribute
Die für UDTs zurückgegebenen Werte sind im Abschnitt "Deskriptorfelder für Ergebnisse" oben erläutert.
SQLColumns
Die für UDTs zurückgegebenen Werte sind wie im Abschnitt "Spaltenmetadaten, die von SQLColumns und SQLProcedureColumns (Katalogmetadaten)" weiter oben in diesem Thema zurückgegeben werden, beschrieben.
SQLDescribeCol
Für UDTs werden folgende Werte zurückgegeben:
| SQL-Datentyp | DataTypePtr | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (Länge größer als 8.000 Bytes) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLDescribeParam
Für UDTs werden folgende Werte zurückgegeben:
| SQL-Datentyp | DataTypePtr | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (Länge größer als 8.000 Bytes) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLFetch
UDT-Ergebnisspaltenwerte werden von SQL in C-Datentypen konvertiert, wie im Abschnitt "Bindungen und Konvertierungen" weiter oben in diesem Thema beschrieben.
SQLFetchScroll
UDT-Ergebnisspaltenwerte werden von SQL in C-Datentypen konvertiert, wie im Abschnitt "Bindungen und Konvertierungen" weiter oben in diesem Thema beschrieben.
SQLGetData
UDT-Ergebnisspaltenwerte werden von SQL in C-Datentypen konvertiert, wie im Abschnitt "Bindungen und Konvertierungen" weiter oben in diesem Thema beschrieben.
SQLGetDescField
Die für die neuen Datentypen verfügbaren Deskriptorfelder sind in den Abschnitten "Deskriptorfelder für Parameter" und "Deskriptorfelder für Ergebnisse" oben erläutert.
SQLGetDescRec
Für UDTs werden folgende Werte zurückgegeben:
| SQL-Datentyp | type | Untertyp | Length | Genauigkeit | Skalierung |
|---|---|---|---|---|---|
| SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT | 0 | n | n | 0 |
| SQL_SS_UDT (Länge größer als 8.000 Bytes) |
SQL_SS_UDT | 0 | SQL_SS_LENGTH_UNLIMITED (0) | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLGetTypeInfo
Die für UDTs zurückgegebenen Werte sind im Abschnitt "Von SQLColumns und SQLProcedureColumns zurückgegebene Spaltenmetadaten (Katalogmetadaten)" oben erläutert.
SQLProcedureColumns
Die für UDTs zurückgegebenen Werte sind im Abschnitt "Von SQLColumns und SQLProcedureColumns zurückgegebene Spaltenmetadaten (Katalogmetadaten)" oben erläutert.
SQLPutData
UDT-Parameterwerte werden von C in SQL-Datentypen konvertiert, wie im Abschnitt "Bindungen und Konvertierungen" weiter oben in diesem Thema beschrieben.
SQLSetDescField
Beschreibungsfeld, das für die neuen Typen verfügbar ist, werden weiter oben in diesem Thema in den Abschnitten "Descriptor Fields for Parameters" und "Descriptor Fields for Results" beschrieben.
SQLSetDescRec
Die zulässigen Werte für UDTs lauten wie folgt:
| SQL-Datentyp | type | Untertyp | Length | Genauigkeit | Skalierung |
|---|---|---|---|---|---|
| SQL_SS_UDT (Länge kleiner oder gleich 8.000 Bytes) |
SQL_SS_UDT | 0 | n | n | 0 |
| SQL_SS_UDT (Länge größer als 8.000 Bytes) |
SQL_SS_UDT | 0 | SQL_SS_LENGTH_UNLIMITED (0) | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
'SQLSpecialColumns'
Die für die Spalten DATA_TYPE, TYPE_NAME, COLUMN_SIZE, BUFFER_LENGTH und DECIMAL_DIGTS zurückgegebenen UDT-Werte sind im Abschnitt "Von SQLColumns und SQLProcedureColumns zurückgegebene Spaltenmetadaten (Katalogmetadaten)" oben erläutert.