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を返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、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 パターン値 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 で再度呼び出されました。 関数が呼び出され、実行が完了する前に、SQLCancel または SQLCancelHandle がマルチスレッド アプリケーション内の別のスレッドから StatementHandle で呼び出されました。 |
| 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 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を使用して設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。 | ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、 後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
Comments
アプリケーションは 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 関数 |