SQLPrepare 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: 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を返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle の Handle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLPrepare によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 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パターン値ESCAPEエスケープ文字" が含まれており、パターン値のエスケープ文字の後の文字は "%" でも "_" でもありません。 |
| 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 に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、StatementHandle で SQLCancel または SQLCancelHandle が呼び出され、その後、その関数が StatementHandle で再度呼び出されました。 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY009 | null ポインターの使用が無効です | (DM) StatementText が null ポインターでした。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLPrepare 関数が呼び出されたときにも実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、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 | タイムアウトに達しました | タイムアウト期間は、データ ソースから結果セットが返される前に期限切れになりました。 タイムアウト期間は、 SQLSetStmtAttr (SQL_ATTR_QUERY_TIMEOUT) によって設定されます。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルを使用するたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する以前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
説明
アプリケーションは SQLPrepare を呼び出して、準備のために SQL ステートメントをデータ ソースに送信します。 準備された実行の詳細については、「準備 された実行」を参照してください。 アプリケーションは、SQL ステートメントに 1 つ以上のパラメーター マーカーを含めることができます。 パラメーター マーカーを含めるために、アプリケーションは疑問符 (?) を適切な位置にある SQL 文字列に埋め込みます。 パラメーターの詳細については、「 ステートメント パラメーター」を参照してください。
Note
アプリケーションで SQLPrepare を使用して準備し、 SQLExecute を使用して COMMIT または ROLLBACK ステートメントを送信する場合、DBMS 製品間で相互運用することはできません。 トランザクションをコミットまたはロールバックするには、 SQLEndTran を呼び出します。
ドライバーは、データ ソースで使用される SQL の形式を使用するように ステートメントを変更し、準備のためにデータ ソースに送信できます。 特に、ドライバーは、特定の機能の SQL 構文を定義するために使用されるエスケープ シーケンスを変更します。 (SQL ステートメント文法の説明については、「ODBC の エスケープ シーケンス 」および 「付録 C: SQL 文法」を参照してください。ドライバーの場合、ステートメント ハンドルは、埋め込み SQL コードのステートメント識別子に似ています。 データ ソースがステートメント識別子をサポートしている場合、ドライバーはステートメント識別子とパラメーター値をデータ ソースに送信できます。
ステートメントが準備されると、アプリケーションはステートメント ハンドルを使用して、後の関数呼び出しで ステートメントを参照します。 ステートメント ハンドルに関連付けられている準備済みステートメントは、 sqlExecute を呼び出すことで再実行できます。このステートメントは、アプリケーションが sqlFreeStmt への呼び出しで SQL_DROP オプションを使用してステートメントを解放するか、 SQLPrepare、 SQLExecDirect、またはカタログ関数 (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 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示