SQL Server Native Client でのユーザー定義型の使用
適用対象: 
SQL Server Azure SQL Database 
Azure Synapse Analytics Analytics Platform System (PDW)
重要
SQL Server Native Client (SNAC) は同梱されていません。
- SQL Server 2022 (16.x) 以降のバージョン
- SQL Server Management Studio (19 以降のバージョン) の場合
SQL Server Native Client (SQLNCLI または SQLNCLI11) とレガシ Microsoft OLE DB Provider for SQL Server (SQLOLEDB) は、新しいアプリケーション開発には推奨されません。
新しいプロジェクトの場合は、次のいずれかのドライバーを使用します。
SQL Server データベース エンジン (バージョン 2012 から 2019) のコンポーネントとして付属する SQLNCLI については、この「サポート ライフサイクルの例外」を参照してください。
SQL Server 2005 (9.x) では、ユーザー定義型 (UDT) が導入されました。 これにより、SQL Server データベースにオブジェクトやカスタム データ構造を格納できるようになり、SQL の型システムが拡張されます。 UDT は複数のデータ型を持つことができ、動作を定義できます。この点は、1 つの SQL Server システム データ型から構成される従来の別名データ型と異なります。 UDT は、検証可能なコードを生成する .NET 共通言語ランタイム (CLR) でサポートされる任意の言語を使用して定義されます。 これには、C# と Visual Basic .NET が含まれます。 データは、.NET のクラスまたは構造体のフィールドやプロパティとして公開され、動作はクラスまたは構造体のメソッドによって定義されます。
UDT は、テーブルの列定義、Transact-SQL バッチの変数、または Transact-SQL 関数やストアド プロシージャの引数として使用できます。
SQL Server Native Client OLE DB プロバイダー
SQL Server Native Client OLE DB プロバイダーは、UDT をバイナリ型としてサポートし、メタデータ情報を使用して UDT をオブジェクトとして管理できます。 UDT 列は、DBTYPE_UDT 型として公開され、この列のメタデータは主要な OLE DB インターフェイスの IColumnRowset と新しいインターフェイスの ISSCommandWithParameters により公開されます。
注意
IRowsetFind::FindNextRow メソッドでは、UDT データ型を処理できません。 UDT が検索列の型として使用されると、DB_E_BADCOMPAREOP が返されます。
データ バインドと強制型変換
次の表に、特定のデータ型を SQL Server の UDT と共に使用した場合に行われるバインドおよび強制型変換を示します。 UDT 列は、SQL Server Native Client OLE DB プロバイダーを介してDBTYPE_UDTとして公開されます。 この列のメタデータは、適切なスキーマ行セットを使用して取得できるので、独自に定義した型をオブジェクトとして管理できます。
| データ型 | SQL Server の UDT |
SQL Server の UDT 以外から |
サーバーからの UDT |
サーバーからの UDT 以外から |
|---|---|---|---|---|
| DBTYPE_UDT | サポートされている6 | エラー1 | サポートされている6 | エラー5 |
| DBTYPE_BYTES | サポートされている6 | N/A2 | サポートされている6 | N/A2 |
| DBTYPE_WSTR | サポートされている3、6 | N/A2 | サポートされている4、6 | N/A2 |
| DBTYPE_BSTR | サポートされている3、6 | N/A2 | サポートされている4 | N/A2 |
| DBTYPE_STR | サポートされている3、6 | N/A2 | サポートされている4、6 | N/A2 |
| DBTYPE_IUNKNOWN | サポートされていません | N/A2 | サポートされていません | N/A2 |
| DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) | サポートされている6 | N/A2 | サポートされている4 | N/A2 |
| DBTYPE_VARIANT (VT_BSTR) | サポートされている3、6 | N/A2 | 該当なし | N/A2 |
1ICommandWithParameters::SetParameterInfo で DBTYPE_UDT 以外のサーバーの型が指定され、アクセサーの型が DBTYPE_UDT の場合、ステートメントの実行時にエラー (DB_E_ERRORSOCCURRED) が発生します (パラメーターの状態は DBSTATUS_E_BADACCESSOR になります)。 それ以外の場合、データはサーバーに送信されますが、サーバーからは、UDT からパラメーターのデータ型への暗黙的な変換がないことを示すエラーが返されます。
2このトピックの範囲を説明します。
3 16 進文字列からバイナリ データへのデータ変換が行われます。
4 バイナリ データから 16 進文字列へのデータ変換が行われます。
5アクセサーの作成時またはフェッチ時に検証が行われることがあります。エラー DB_E_ERRORSOCCURRED が返され、バインドの状態は DBBINDSTATUS_UNSUPPORTEDCONVERSION になります。
6BY_REF を使用できます。
DBTYPE_NULL と DBTYPE_EMPTY は入力パラメーターにバインドできますが、出力パラメーターや結果にはバインドできません。 入力パラメーターにバインドした場合、状態を DBSTATUS_S_ISNULL または DBSTATUS_S_DEFAULT に設定する必要があります。
DBTYPE_UDT 型は、DBTYPE_EMPTY と DBTYPE_NULL に変換できますが、DBTYPE_EMPTY と DBTYPE_NULL は DBTYPE_UDT に変換できません。 この動作は、DBTYPE_BYTES 型と一貫性があります。
Note
UDT をパラメーターとして処理するための新しいインターフェイス ISSCommandWithParameters が導入されました。これは、ICommandWithParameters インターフェイスから継承されます。 アプリケーションでは、少なくとも UDT パラメーターの SSPROP_PARAM_UDT_NAME プロパティ セットの DBPROPSET_SQLSERVERPARAMETER プロパティの設定に、このインターフェイスを使用する必要があります。 これを行わないと、ICommand::Execute から DB_E_ERRORSOCCURRED が返されます。 このインターフェイスとプロパティ セットについては、このトピックの後半で説明します。
データをすべて格納できる大きさがない列にユーザー定義型を挿入した場合、ICommand::Execute は状態が DB_E_ERRORSOCCURRED の S_OK を返します。
OLE DB Core Services で提供されるデータ変換 (IDataConvert) は、DBTYPE_UDT 型には適用できません。 また、その他のバインドもサポートされません。
OLE DB 行セットに関する追加事項と変更事項
SQL Server Native Client は、多くの主要な OLE DB スキーマ行セットに新しい値または変更を追加します。
PROCEDURE_PARAMETERS スキーマ行セット
PROCEDURE_PARAMETERS スキーマ行セットには、次の列が追加されました。
| 列名 | 種類 | 説明 |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | 3 部構成の名前の識別子。 |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | 3 部構成の名前の識別子。 |
| SS_UDT_NAME | DBTYPE_WSTR | 3 部構成の名前の識別子。 |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | 型名と、CLR での参照に必要なすべてのアセンブリ ID を含むアセンブリ修飾名。 |
SQL_ASSEMBLIES スキーマ行セット
SQL Server Native Client OLE DB プロバイダーは、登録済みの UDT を記述する新しいプロバイダー固有のスキーマ行セットを公開します。 ASSEMBLY_SERVER を DBTYPE_WSTR 型として指定することはできますが、行セットには格納されません。 指定しない場合、行セットでは既定で現在のサーバーが使用されます。 次の表に、SQL_ASSEMBLIES スキーマ行セットの定義を示します。
| 列名 | 種類 | 説明 |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | このデータ型を含むアセンブリのカタログ名。 |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | このデータ型を含むアセンブリのスキーマ名 (所有者の名前)。 アセンブリのスコープはスキーマではなくデータベースによって決まりますが、アセンブリには依然として所有者が存在します。 |
| ASSEMBLY_NAME | DBTYPE_WSTR | このデータ型を含むアセンブリの名前。 |
| ASSEMBLY_ID | DBTYPE_UI4 | このデータ型を含むアセンブリのオブジェクト ID。 |
| PERMISSION_SET | DBTYPE_WSTR | アセンブリのアクセスのスコープを示す値。 スコープを示す値には、"SAFE"、"EXTERNAL_ACCESS"、および "UNSAFE" があります。 |
| ASSEMBLY_BINARY | DBTYPE_BYTES | アセンブリのバイナリ表記。 |
SQL_ASSEMBLIES_ DEPENDENCIES スキーマ行セット
SQL Server Native Client OLE DB プロバイダーは、指定されたサーバーのアセンブリの依存関係を記述する新しいプロバイダー固有のスキーマ行セットを公開します。 ASSEMBLY_SERVER は呼び出し元により DBTYPE_WSTR 型として指定することができますが、行セットには格納されません。 指定しない場合、行セットでは既定で現在のサーバーが使用されます。 次の表に、SQL_ASSEMBLY_DEPENDENCIES スキーマ行セットの定義を示します。
| 列名 | 種類 | 説明 |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | このデータ型を含むアセンブリのカタログ名。 |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | このデータ型を含むアセンブリのスキーマ名 (所有者の名前)。 アセンブリのスコープはスキーマではなくデータベースによって決まりますが、アセンブリには依然として所有者が存在します。 |
| ASSEMBLY_ID | DBTYPE_UI4 | アセンブリのオブジェクト ID。 |
| REFERENCED_ASSEMBLY_ID | DBTYPE_UI4 | 参照されるアセンブリのオブジェクト ID。 |
SQL_USER_TYPES スキーマ行セット
SQL Server Native Client OLE DB プロバイダーは、新しいスキーマ行セット (SQL_USER_TYPES) を公開します。これは、指定されたサーバーに登録されている UDT が追加されるタイミングを記述します。 UDT_SERVER は、呼び出し元により DBTYPE_WSTR 型として指定される必要がありますが、行セットには格納されません。 次の表に、SQL_USER_TYPES スキーマ行セットの定義を示します。
| 列名 | 種類 | 説明 |
|---|---|---|
| UDT_CATALOGNAME | DBTYPE_WSTR | UDT 列の場合、このプロパティは、UDT が定義されているカタログ名を指定する文字列です。 |
| UDT_SCHEMANAME | DBTYPE_WSTR | UDT 列の場合、このプロパティは、UDT が定義されているスキーマ名を指定する文字列です。 |
| UDT_NAME | DBTYPE_WSTR | UDT を含むアセンブリの名前。 |
| UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | 型名の前に名前空間を付けた完全な型名 (AQN) (該当する場合)。 |
COLUMNS スキーマ行セット
COLUMNS スキーマ行セットには、次の列が追加されました。
| 列名 | 種類 | 説明 |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | UDT 列の場合、このプロパティは、UDT が定義されているカタログ名を指定する文字列です。 |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | UDT 列の場合、このプロパティは、UDT が定義されているスキーマ名を指定する文字列です。 |
| SS_UDT_NAME | DBTYPE_WSTR | UDT の名前。 |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | 型名の前に名前空間を付けた完全な型名 (AQN) (該当する場合)。 |
OLE DB プロパティ セットに関する追加事項と変更事項
SQL Server Native Client は、多くの主要な OLE DB プロパティ セットに新しい値または変更を追加します。
DBPROPSET_SQLSERVERPARAMETER プロパティ セット
OLE DB を介して UDT をサポートするために、SQL Server Native Client は、次の値を含む新しいDBPROPSET_SQLSERVERPARAMETER プロパティ セットを実装します。
| 名前 | 種類 | 説明 |
|---|---|---|
| SSPROP_PARAM_UDT_CATALOGNAME | DBTYPE_WSTR | 3 部構成の名前の識別子。 UDT パラメーターの場合、このプロパティは、ユーザー定義型が定義されているカタログ名を指定する文字列です。 |
| SSPROP_PARAM_UDT_SCHEMANAME | DBTYPE_WSTR | 3 部構成の名前の識別子。 UDT パラメーターの場合、このプロパティは、ユーザー定義型が定義されているスキーマ名を指定する文字列です。 |
| SSPROP_PARAM_UDT_NAME | DBTYPE_WSTR | 3 部構成の名前の識別子。 UDT 列の場合、このプロパティは、ユーザー定義型の 1 部構成の名前を指定する文字列です。 |
SSPROP_PARAM_UDT_NAME は必須です。 SSPROP_PARAM_UDT_CATALOGNAME と SSPROP_PARAM_UDT_SCHEMANAME は省略可能です。 いずれかのプロパティが適切に指定されていない場合、DB_E_ERRORSINCOMMAND が返されます。 SSPROP_PARAM_UDT_CATALOGNAME プロパティと SSPROP_PARAM_UDT_SCHEMANAME プロパティがどちらも指定されていない場合、UDT は、テーブルと同じデータベースおよびスキーマ内に定義する必要があります。 UDT の定義が、テーブルと同じデータベース内にあって、同じスキーマ内にない場合、SSPROP_PARAM_UDT_SCHEMANAME プロパティを指定する必要があります。 UDT の定義がテーブルと異なるデータベースにある場合、SSPROP_PARAM_UDT_CATALOGNAME プロパティと SSPROP_PARAM_UDT_SCHEMANAME プロパティの両方を指定する必要があります。
DBPROPSET_SQLSERVERCOLUMN プロパティ セット
ITableDefinition インターフェイスでのテーブルの作成をサポートするために、SQL Server Native Client は、DBPROPSET_SQLSERVERCOLUMN プロパティ セットに次の 3 つの新しい列を追加します。
| 名前 | Description | Type | 説明 |
|---|---|---|---|
| SSPROP_COL_UDT_CATALOGNAME | UDT_CATALOGNAME | VT_BSTR | DBTYPE_UDT 型の列の場合、このプロパティは、UDT が定義されているカタログ名を指定する文字列です。 |
| SSPROP_COL_UDT_SCHEMANAME | UDT_SCHEMANAME | VT_BSTR | DBTYPE_UDT 型の列の場合、このプロパティは、UDT が定義されているスキーマ名を指定する文字列です。 |
| SSPROP_COL_UDT_NAME | UDT_NAME | VT_BSTR | DBTYPE_UDT 型の列の場合、このプロパティは、UDT の 1 部構成の名前を指定する文字列です。 他の列の型の場合、このプロパティでは空文字列が返されます。 |
Note
UDT は PROVIDER_TYPES スキーマ行セットには表示されません。 すべての列は読み取り/書き込みアクセスです。
ADO では、"説明" 列の対応するエントリを使用してこれらのプロパティを参照します。
SSPROP_COL_UDTNAME は必須です。 SSPROP_COL_UDT_CATALOGNAME と SSPROP_COL_UDT_SCHEMANAME は省略可能です。 いずれかのプロパティが適切に指定されていない場合、DB_E_ERRORSINCOMMAND が返されます。
SSPROP_COL_UDT_CATALOGNAME プロパティと SSPROP_COL_UDT_SCHEMANAME プロパティがどちらも指定されていない場合、UDT は、テーブルと同じデータベースおよびスキーマ内に定義する必要があります。
UDT の定義が、テーブルと同じデータベース内にあって、同じスキーマ内にない場合、SSPROP_COL_UDT_SCHEMANAME プロパティを指定する必要があります。
UDT の定義がテーブルと異なるデータベースにある場合、SSPROP_COL_UDT_CATALOGNAME プロパティと SSPROP_COL_UDT_SCHEMANAME プロパティの両方を指定する必要があります。
OLE DB インターフェイスに関する追加事項と変更事項
SQL Server Native Client は、多くの主要な OLE DB インターフェイスに新しい値または変更を追加します。
ISSCommandWithParameters インターフェイス
OLE DB を介して UDT をサポートするために、SQL Server Native Client では、 ISSCommandWithParameters インターフェイスの追加など、さまざまな変更が実装されています。 この新しいインターフェイスは、主要な OLE DB インターフェイス ICommandWithParameters から継承されます。 ICommandWithParameters; から継承された 3 つのメソッドに加えて、GetParameterInfo、MapParameterNames、および SetParameterInfo; ISSCommandWithParameters はGetParameterPropertiesおよび SetParameterProperties サーバー固有のデータ型の処理に使用されるメソッドを提供します。
Note
ISSCommandWithParameters インターフェイスでは、新しい SSPARAMPROPS 構造体も使用されます。
IColumnsRowset インターフェイス
| 列名 | 種類 | 説明 |
|---|---|---|
| DBCOLUMN_SS_UDT_CATALOGNAME | DBTYPE_WSTR | UDT カタログ名の識別子。 |
| DBCOLUMN_SS_UDT_SCHEMANAME | DBTYPE_WSTR | UDT スキーマ名の識別子。 |
| DBCOLUMN_SS_UDT_NAME | DBTYPE_WSTR | UDT 名の識別子。 |
| DBCOLUMN_SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | 型名と、CLR での参照に必要なすべてのアセンブリ ID を含むアセンブリ修飾名。 |
DBCOLUMN_TYPE を DBTYPE_UDT に設定すると、上記の新しく追加された UDT メタデータを参照することにより、サーバーの UDT 列と他のバイナリ型列とを区別することができます。 そのデータが部分的に完成している場合、サーバーのデータ型は UDT になります。 サーバーのデータ型が UDT 以外の場合、これらの列は、常に NULL として返されます。
SQL Server Native Client ODBC ドライバー
UDT をサポートするために、SQL Server Native Client ODBC ドライバーでいくつかの変更が行われました。 SQL Server Native Client ODBC ドライバーは、SQL Server UDT をドライバー固有の SQL データ型識別子SQL_SS_UDTマップします。 UDT 列は SQL_SS_UDT 型としてマップされます。 UDT の ToString または ToXMLString メソッド、または CAST/CONVERT 関数を使用して、SQL ステートメント内の別の型に UDT 列を明示的にマップする場合、結果セット内の列の型には、列が変換された実際の型が反映されます。
SQLColAttribute、SQLDescribeParam、SQLGetDescField
SQLColAttribute、SQLDescribeParam、および SQLGetDescField 関数を使用して取得する、結果セットの UDT 列またはストアド プロシージャ/パラメーター化クエリの UDT パラメーターに関する追加情報を提供するために、4 つの新しいドライバー固有の記述子フィールドが追加されました。
新しく追加された記述子フィールドは、SQL_CA_SS_UDT_CATALOG_NAME、SQL_CA_SS_UDT_SCHEMA_NAME、SQL_CA_SS_UDT_TYPE_NAME、および SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME です。
SQLColumns、SQLProcedureColumns
さらに、
サポートされる変換
SQL データ型から C データ型に変換する際、SQL_C_WCHAR、SQL_C_BINARY、および SQL_C_CHAR は、すべて SQL_SS_UDT に変換できます。 ただし、SQL_C_WCHAR と SQL_C_CHAR SQL から変換した場合、バイナリ データは 16 進文字列に変換されることに注意してください。
C データ型から SQL データ型に変換する際、SQL_C_WCHAR、SQL_C_BINARY、および SQL_C_CHAR は、すべて SQL_SS_UDT に変換できます。 ただし、バイナリ データは、SQL_C_WCHARから変換するときに 16 進文字列に変換され、SQL データ型SQL_C_CHARされることに注意してください。
参照
SQL Server Native Client の機能
ISSCommandWithParameters (OLE DB)