SQLPrepare 関数

準拠
導入されたバージョン: ODBC 1.0 標準コンプライアンス: ISO 92

まとめ
SQLPrepare は実行用に SQL 文字列を準備します。

構文

  
SQLRETURN SQLPrepare(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     StatementText,  
     SQLINTEGER    TextLength);  

引数

StatementHandle
[入力]ステートメント ハンドル。

StatementText
[入力]SQL テキスト文字列。

TextLength
[入力]*StatementText の文字数。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLPrepareがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合は、SQL_HANDLE_STMTのHandleTypeとStatementHandleのHandleを使用してSQLGetDiagRecを呼び出すことによって、関連付けられた SQLSTATE 値を取得できます。 次の表に、 SQLPrepare によって一般的に返される SQLSTATE 値を示しこの関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATE の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

SQLSTATE	エラー	説明
01000	一般的な警告	ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S02	オプション値の変更	指定されたステートメント属性は、実装の作業条件のために無効であるため、同様の値が一時的に置き換えられました。 (SQLGetStmtAttr を呼び出して、一時的に置換された値が何であるかを判断できます)。置き換える値は、カーソルが閉じられるまで、 StatementHandle に対して有効です。 変更できるステートメント属性は次のとおりです:SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR (関数はSQL_SUCCESS_WITH_INFOを返します。
08S01	通信リンクエラー	ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。
21S01	挿入する値の一覧が列の一覧と一致しません	*StatementText には INSERT ステートメントが含まれており、挿入する値の数が派生テーブルの次数と一致しませんでした。
21S02	派生テーブルの次数が列リストと一致しない	*StatementText には CREATE VIEW ステートメントが含まれており、指定された名前の数が、クエリ仕様で定義されている派生テーブルと同じではありません。
22018	キャスト指定の文字値が無効です	*StatementText には、リテラルまたはパラメーターを含む SQL ステートメントが含まれており、値が関連付けられているテーブル列のデータ型と互換性がありません。
22019	エスケープ文字が無効です	引数 StatementTextには、WHERE 句に ESCAPE を持つ LIKE 述語が含まれており、ESCAPE の後のエスケープ文字の長さが 1 に等しくありません。
22025	エスケープ シーケンスが無効です	引数 StatementText WHERE 句に "LIKE pattern value ESCAPE escape character" が含まれ、パターン値のエスケープ文字の後の文字は "%" でも "_" でもありません。
24000	カーソル状態が無効	(DM) StatementHandle でカーソルが開き、 SQLFetch または SQLFetchScroll が呼び出されました。 StatementHandle でカーソルが開かれていましたが、SQLFetch または SQLFetchScrollが呼び出されませんでした。
34000	カーソル名が無効	*StatementText には、配置された DELETE または配置された UPDATEが含まれており、準備中のステートメントによって参照されるカーソルが開いていません。
3D000	カタログ名が無効です	StatementText で指定されたカタログ名が無効でした。
3F000	無効なスキーマ名	StatementText で指定されたスキーマ名が無効でした。
42000	構文エラーまたはアクセス違反	*StatementText には、準備できなかった SQL ステートメント、または構文エラーが含まれていました。 *StatementText には、ユーザーが必要な特権を持っていないステートメントが含まれていました。
42S01	ベース テーブルまたはビューが既に存在する	*StatementText には、 CREATE TABLE または CREATE VIEW ステートメントが含まれており、指定されたテーブル名またはビュー名が既に存在します。
42S02	ベース テーブルまたはビューが見つかりません	*StatementText には、 DROP TABLE または DROP VIEW ステートメントが含まれており、指定したテーブル名またはビュー名が存在しませんでした。 *StatementText には ALTER TABLE ステートメントが含まれており、指定したテーブル名が存在しませんでした。 *StatementText には CREATE VIEW ステートメントが含まれており、クエリ指定で定義されたテーブル名またはビュー名が存在しませんでした。 *StatementText には CREATE INDEX ステートメントが含まれており、指定されたテーブル名が存在しませんでした。 *StatementText には GRANT または REVOKE ステートメントが含まれており、指定されたテーブル名またはビュー名が存在しませんでした。 *StatementText には SELECT ステートメントが含まれており、指定したテーブル名またはビュー名が存在しませんでした。 *StatementText には、 DELETE、 INSERT、または UPDATE ステートメントが含まれており、指定されたテーブル名が存在しませんでした。 *StatementText には CREATE TABLE ステートメントが含まれており、制約で指定されたテーブル (作成されているテーブル以外のテーブルを参照する) が存在しませんでした。
42S11	インデックスは既に存在します	*StatementText には CREATE INDEX ステートメントが含まれており、指定したインデックス名が既に存在しています。
42S12	インデックスが見つかりません	*StatementText には DROP INDEX ステートメントが含まれており、指定したインデックス名が存在しませんでした。
42S21	列は既に存在します	*StatementText ALTER TABLE ステートメントが含まれており、 ADD 句で指定された列が一意ではないか、ベース テーブル内の既存の列を識別します。
42S22	列が見つかりません	*StatementText には CREATE INDEX ステートメントが含まれており、列リストに指定された 1 つ以上の列名が存在しませんでした。 *StatementText には GRANT または REVOKE ステートメントが含まれており、指定された列名が存在しませんでした。 *StatementText には、 SELECT、 DELETE、 INSERT、または UPDATE ステートメントが含まれており、指定された列名が存在しませんでした。 *StatementText には CREATE TABLE ステートメントが含まれており、制約で指定された列 (作成されるテーブル以外のテーブルを参照する) が存在しませんでした。
HY000	一般的なエラー	特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。
HY001	メモリ割り当てエラー	ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。
HY008	操作が取り消されました	StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandle が StatementHandle で呼び出され、 StatementHandle で関数が再度呼び出されました。 関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandle がマルチスレッド アプリケーション内の別のスレッドから StatementHandle で呼び出されました。
HY009	null ポインターの使用が無効です	(DM) StatementText は null ポインターでした。
HY010	関数シーケンス エラー	(DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLPrepare 関数が呼び出されたときにまだ実行されていました。 (DM) SQLExecute、 SQLExecDirect、または SQLMoreResults StatementHandle が呼び出され、SQL_PARAM_DATA_AVAILABLEが返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではない) が StatementHandle に対して呼び出されこの関数が呼び出されたときにはまだ実行されていました。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations、または SQLSetPos が StatementHandle に対して呼び出され、SQL_NEED_DATAが返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013	メモリ管理エラー	メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY090	文字列またはバッファーの長さが無効です	(DM) 引数 TextLength は 0 以下でしたが、SQL_NTSと等しくありません。
HY117	不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。	(DM) 中断状態の詳細については、「 SQLEndTran 関数を参照してください。
HYC00	省略可能な機能が実装されていません	定義されたカーソルの種類に対してコンカレンシー設定が無効でした。 SQL_ATTR_USE_BOOKMARKS ステートメント属性はSQL_UB_VARIABLEに設定され、SQL_ATTR_CURSOR_TYPE ステートメント属性は、ドライバーがブックマークをサポートしていないカーソルの種類に設定されました。
HYT00	タイムアウトの期限が切れました	データ ソースが結果セットを返す前にタイムアウト期間が経過しました。 タイムアウト期間は、SQL_ATTR_QUERY_TIMEOUT SQLSetStmtAttr によって設定されます。
HYT01	接続のタイムアウト	データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr によって設定されます。
IM001	ドライバーは、この関数をサポートしていません	(DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。
IM017	非同期通知モードでポーリングが無効になっている	通知モデルが使用されるたびに、ポーリングは無効になります。
IM018	SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。	ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。

Comments

アプリケーションは SQLPrepare を呼び出して、準備のために SQL ステートメントをデータ ソースに送信します。 準備された実行の詳細については、「 Prepared Execution」を参照してください。 アプリケーションは、SQL ステートメントに 1 つ以上のパラメーター マーカーを含めることができます。 パラメーター マーカーを含めるために、アプリケーションは疑問符 (?) を適切な位置にある SQL 文字列に埋め込みます。 パラメーターの詳細については、「 Statement パラメーター」を参照してください。

Note

アプリケーションが SQLPrepare を使用して、COMMIT または ROLLBACK ステートメントを送信するために、SQLExecute を準備してする場合、DBMS 製品間で相互運用することはできません。 トランザクションをコミットまたはロールバックするには、 SQLEndTran を呼び出します。

ドライバーは、データ ソースによって使用される SQL の形式を使用するようにステートメントを変更し、準備のためにデータ ソースに送信できます。 特に、ドライバーは、特定の機能の SQL 構文を定義するために使用されるエスケープ シーケンスを変更します。 (SQL ステートメント文法の説明については、 を参照してください。ODBC および Appendix C: SQL Grammar) のエスケープ シーケンス。ドライバーの場合、ステートメント ハンドルは、埋め込み SQL コード内のステートメント識別子に似ています。 データ ソースがステートメント識別子をサポートしている場合、ドライバーはステートメント識別子とパラメーター値をデータ ソースに送信できます。

ステートメントが準備されると、アプリケーションはステートメント ハンドルを使用して、後の関数呼び出しでステートメントを参照します。 ステートメント ハンドルに関連付けられている準備済みステートメントは、SQLExecuteを呼び出すことによって再実行できます。このステートメントはSQL_DROPオプションを指定してSQLFreeStmt の呼び出しでステートメントを解放するかSQLPrepare の呼び出しでステートメント ハンドルが使用されるまで SQLExecDirect、またはカタログ関数の 1 つ (SQLColumns、SQLTables など)。 アプリケーションは、ステートメントを準備したら、結果セットの形式に関する情報を要求できます。 一部の実装では、SQLPrepare の後にSQLDescribeColまたはSQLDescribeParamを呼び出すとSQLExecuteまたはSQLExecDirect後に関数を呼び出すほど効率的でない場合があります。

一部のドライバーは、アプリケーションが SQLPrepare を呼び出すときに構文エラーやアクセス違反を返すことができません。 ドライバーは、構文エラーとアクセス違反、構文エラーのみ、または構文エラーもアクセス違反も処理できません。 そのため、アプリケーションは、 SQLNumResultCols、 SQLDescribeCol、 SQLColAttribute、 SQLExecute などの後続の関連関数を呼び出すときに、これらの条件を処理できる必要があります。

ドライバーとデータ ソースの機能によっては、ステートメントの準備時 (すべてのパラメーターがバインドされている場合) または実行時 (すべてのパラメーターがバインドされていない場合) に、パラメーター情報 (データ型など) がチェックされる場合があります。 相互運用性を最大限に高めるために、アプリケーションは、同じステートメントで新しい SQL ステートメントを準備する前に、古い SQL ステートメントに適用されたすべてのパラメーターのバインドを解除する必要があります。 これにより、古いパラメーター情報が新しいステートメントに適用されたことが原因で発生するエラーが回避されます。

重要

SQLEndTran を明示的に呼び出すか自動コミット モードで作業することによって、トランザクションをコミットすると、データ ソースが接続上のすべてのステートメントのアクセス プランを削除する可能性があります。 詳細については、 SQLGetInfo のSQL_CURSOR_COMMIT_BEHAVIORとSQL_CURSOR_ROLLBACK_BEHAVIORの情報の種類 および カーソルおよび準備されたステートメントのトランザクションの効果を参照してください。

コード例

SQLBindParameter、SQLPutData、および SQLSetPos を参照してください。

関連する関数

情報	参照トピック
ステートメント ハンドルの割り当て	SQLAllocHandle 関数
結果セット内の列へのバッファーのバインド	SQLBindCol 関数
バッファーをパラメーターにバインドする	SQLBindParameter 関数
ステートメント処理の取り消し	SQLCancel 関数
コミットまたはロールバック操作の実行	SQLEndTran 関数
SQL ステートメントの実行	SQLExecDirect 関数
準備された SQL ステートメントの実行	SQLExecute 関数
ステートメントの影響を受ける行数を返す	SQLRowCount 関数
カーソル名の設定	SQLSetCursorName 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル