CLI の手引きおよび解説書

SQLCopyDesc - ハンドル間で記述子情報をコピーする

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLCopyDesc() は、 1 つの記述子ハンドルからもう 1 つの記述子ハンドルへと記述子情報をコピーします。

構文

SQLRETURN   SQLCopyDesc      (SQLHDESC          SourceDescHandle,
                              SQLHDESC          TargetDescHandle);

関数引き数

表 42. SQLCopyDesc 引き数
データ・タイプ 引き数 使用法 説明
SQLHDESC SourceDescHandle 入力 ソース記述子ハンドル
SQLHDESC TargetDescHandle 入力 ターゲット記述子ハンドル。 TargetDescHandle は、アプリケーション記述子または IPD に対するハンドルになり得ます。 SQLCopyDesc() は、TargetDescHandle が IRD に対するハンドルである場合に、 SQLSTATE HY016 を返します (実装記述子を変更することはできません)。

使用法

SQLCopyDesc() を呼び出して、ソース記述子ハンドルのフィールドをターゲット記述子ハンドルにコピーします。フィールドは、アプリケーション記述子または IPD にはコピーできますが、 IRD にはコピーできません。フィールドは、アプリケーション記述子からでも実装記述子からでもコピーできます。

記述子のすべてのフィールドは、 SQL_DESC_ALLOC_TYPE (これは記述子ハンドルが自動的に割り振られたか明示的に割り振られたかを指定します) を除いて、そのフィールドが宛先記述子用に定義されていてもいなくても、コピーされます。コピーされたフィールドは、既存のフィールドを上書きします。

すべての記述子フィールドは、 SourceDescHandleTargetDescHandle が 2 つの異なる接続または環境にある場合でも、コピーされます。

SQLCopyDesc() の呼び出しは、エラーが発生した場合は、直ちに打ち切られます。

SQL_DESC_DATA_PTR フィールドがコピーされるとき、整合性検査が行われます。整合性検査に失敗した場合、SQLSTATE HY021 (記述子情報が不整合です。) が返されて、 SQLCopyDesc() の呼び出しは直ちに打ち切られます。詳細については、『SQLSetDescField()』の中の『整合性検査』を参照してください。

注:記述子ハンドルは、接続または環境を越えてコピーできます。しかし、アプリケーションは、SQLCopyDesc() を呼び出すよりは、明示的に割り振られた記述子ハンドルを StatementHandle に関連付けて、 1 つの記述子からもう 1 つの記述子へとフィールドをコピーできるようにします。明示的に割り振られた記述子は、 SQL_ATTR_APP_ROW_DESC または SQL_ATTR_APP_PARAM_DESC ステートメントを、明示的に割り振られた記述子のハンドルに設定することにより、同じ ConnectionHandle 上の別の StatementHandle に関連付けることができます。これが行われると、 1 つの記述子から別の記述子へ記述子フィールドの値をコピーするために SQLCopyDesc() を呼び出す必要はなくなります。

記述子ハンドルは、もう 1 つ別の ConnectionHandle 上の StatementHandle には関連付けできませんが、異なる ConnectionHandles 上の StatementHandles に同じ記述子フィールド値を使用するには、 SQLCopyDesc() の呼び出しが必要になります。

記述子ヘッダーまたはレコードのフィールドの説明については、 SQLSetDescField - 記述子レコードの単一フィールドを設定するを参照してください。記述子の詳細については、記述子の使用を参照してください。

表の間での行のコピー

1 つのステートメント・ハンドル上の ARD は、別のステートメント・ハンドル上の APD として機能できます。このことから、アプリケーション・レベルでのデータのコピーをしなくても、表間で行のコピーを行うことができます。これを行うには、アプリケーションが SQLCopyDesc() を呼び出して、表から取り出した行を記述する ARD のフィールドを、別のステートメント・ハンドル上の INSERT ステートメントのパラメーター用の APD にコピーします。 SQLGetInfo() の呼び出しに対してドライバーにより返される SQL_ACTIVE_STATEMENTS の InfoType は、後続の操作のために 1 より大きい値にする必要があります。

戻りコード

診断

SQLCopyDesc() が SQL_ERROR または SQL_SUCCESS_WITH_INFO を返すときは、 SQL_HANDLE_DESC の HandleType および TargetDescHandle の Handle を用いて SQLGetDiagRec() を呼び出すことにより、関連した SQLSTATE 値を入手することができます。呼び出しで無効な SourceDescHandle が渡された場合は、 SQL_INVALID_HANDLE が返されますが、SQLSTATE は返されません。

エラーが返されたとき、SQLCopyDesc() の呼び出しは直ちに打ち切られ、 TargetDescHandle 記述子内のフィールドの内容は未定義になります。


表 43. SQLCopyDesc SQLSTATE
SQLSTATE 説明 解説
01000 警告。 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
08S01 通信リンクに障害が起きました。 関数が処理を完了する前に、 DB2 CLI と接続を試行していたデータ・ソースとの間の通信リンクが失敗しました。
HY000 一般的なエラーです。 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。
HY007 関連したステートメントが準備されていません。 SourceDescHandle が IRD と関連付けられましたが、関連したステートメント・ハンドルは、準備または実行状態にありませんでした。
HY010 関数の順序エラーです。

実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。

非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。

HY016 インプリメンテーションの行記述子を変更することはできません。 TargetDescHandle が IRD に関連付けられました。
HY021 記述子情報が不整合です。 整合性検査時に検査された記述子情報は、整合性がとれていませんでした。詳細については、SQLSetDescField() の中の 『整合性検査』を参照してください。
HY092 オプション・タイプが範囲外です。 SQLCopyDesc() の呼び出しにより、 SQLSetDescField() を呼び出すプロンプトが出されましたが、 *ValuePtr は、 TargetDescHandle 上の FieldIdentifier 引き数に対して有効ではありませんでした。

制約

なし。

該当するサンプルの一覧については、 sqllib\samples\cli (または sqllib/samples/cli) サブディレクトリー内の README ファイルを参照してください。

参照

なし。


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]