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 値を取得するには、HandleType のSQL_HANDLE_STMTと StatementHandleハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLPrepare によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 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 句に "LIKEpatternvalueESCAPEescape文字" が含まれており、パターン値のエスケープ文字の後の文字は "%" でも "_" でもありません。
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 ステートメントが含まれており、指定されたテーブル名またはビュー名が存在しませんでした。

*StatementTextALTER TABLE ステートメントが含まれており、指定されたテーブル名が存在しませんでした。

*StatementText には CREATE VIEW ステートメントが含まれており、クエリ仕様で定義されたテーブル名またはビュー名が存在しませんでした。

*StatementTextCREATE INDEX ステートメントが含まれており、指定されたテーブル名が存在しませんでした。

*StatementText には GRANT ステートメントまたは REVOKE ステートメントが含まれており、指定されたテーブル名またはビュー名が存在しませんでした。

*StatementTextSELECT ステートメントが含まれており、指定されたテーブル名またはビュー名が存在しませんでした。

*StatementText には DELETEINSERT、または 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 には SELECTDELETEINSERT、または UPDATE ステートメントが含まれており、指定された列名が存在しませんでした。

*StatementText には CREATE TABLE ステートメントが含まれており、制約で指定された列 (作成されるテーブル以外のテーブルを参照する) は存在しませんでした。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因について説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。
HY008 操作が取り消されました StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 SqlCancel または SQLCancelHandleStatementHandle で呼び出され、その関数が StatementHandle で再度呼び出されました。

関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから StatementHandleSQLCancel または SQLCancelHandle が呼び出されました。
HY009 null ポインターの使用が無効です (DM) StatementText は null ポインターでした。
HY010 関数シーケンス エラー (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期に実行される関数が呼び出されました。 この非同期関数は、 SQLPrepare 関数が呼び出されたときにまだ実行されていました。

(DM) SQLExecuteSQLExecDirect、または SQLMoreResultsStatementHandle に対して呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターに対してデータが取得される前に呼び出されました。

(DM) 非同期で実行される関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにまだ実行されていました。

(DM) SQLExecuteSQLExecDirectSQLBulkOperations、または SQLSetPosStatementHandle に対して呼び出され、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 を呼び出す必要があります。

コメント

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

注意

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

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

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

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

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

重要

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

コード例

SQLBindParameterSQLPutData、および SQLSetPos に関するページを参照してください。

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

参照

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