次の方法で共有

SQLFreeStmt 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92

まとめ
SQLFreeStmt は、特定のステートメントに関連付けられている処理を停止し、ステートメントに関連付けられている開いているカーソルを閉じるか、保留中の結果を破棄するか、または必要に応じて、ステートメント ハンドルに関連付けられているすべてのリソースを解放します。

構文

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);

引数

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

オプション
[入力]次のいずれかのオプションがあります。

SQL_ CLOSE: StatementHandle に関連付けられているカーソルを閉じ (定義されている場合)、保留中のすべての結果を破棄します。 アプリケーションは、同じパラメーター値または異なるパラメーター値を使用して SELECT ステートメントをもう一度実行することで、後でこのカーソルを再度開くことができます。 カーソルが開かなければ、このオプションはアプリケーションに影響しません。 SQLCloseCursor を呼び出してカーソルを閉じることもできます。 詳細については、「 カーソルを閉じる」を参照してください。

SQL_DROP: このオプションは非推奨です。 オプションが SQL_DROP の SQLFreeStmt の呼び出しは、ドライバー マネージャーで SQLFreeHandle にマップされます。

SQL_UNBIND: ARD のSQL_DESC_COUNT フィールドを 0 に設定し、指定された StatementHandle に対して SQLBindCol によってバインドされているすべての列バッファーを解放します。 ブックマーク列のバインドは解除されません。これを行うには、ブックマーク列の ARD のSQL_DESC_DATA_PTR フィールドが NULL に設定されます。 この操作が、複数のステートメントで共有される明示的に割り当てられた記述子に対して実行された場合、その操作は記述子を共有するすべてのステートメントのバインドに影響します。 詳細については、「 結果の取得の概要 (Basic)」を参照してください。

SQL_RESET_PARAMS: APD のSQL_DESC_COUNT フィールドを 0 に設定し、指定された StatementHandle に対して SQLBindParameter によって設定されたすべてのパラメーター バッファーを解放します。 この操作が、複数のステートメントで共有される明示的に割り当てられた記述子に対して実行された場合、この操作は記述子を共有するすべてのステートメントのバインドに影響します。 詳細については、「 バインド パラメーター」を参照してください。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

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

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY010 関数シーケンス エラー (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLFreeStmt が呼び出されたときにも実行されていました。

(DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に 、Option を SQL_RESET_PARAMS に設定して呼び出されました。

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

(DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013 メモリ管理エラー メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY092 オプションの種類が範囲外 (DM) 引数 Option に指定された値は次の値ではありません。

SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。

説明

SQL_CLOSE オプションを使用して SQLFreeStmt を呼び出すことは SQLCloseCursor を呼び出すことと同じですが、SQL_CLOSEを使用した SQLFreeStmt は、ステートメントでカーソルが開かれない場合はアプリケーションに影響しません。 カーソルが開かっていない場合、 SQLCloseCursor の呼び出しは SQLSTATE 24000 (無効なカーソル状態) を返します。

アプリケーションでは、解放後にステートメント ハンドルを使用しないでください。ドライバー マネージャーは、関数呼び出しでハンドルの有効性を確認しません。

例

ハンドルを解放することをお勧めします。 ただし、わかりやすくするために、次のサンプルには、割り当てられたハンドルを解放するコードは含まれていません。 ハンドルを解放する方法の例については、「 SQLFreeHandle 関数」を参照してください。

// SQLFreeStmt.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   // declare and initialize the environment, connection, statement handles  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
   retCode = SQLFreeStmt(hstmt, SQL_UNBIND);  
   retCode = SQLFreeStmt(hstmt, SQL_RESET_PARAMS);  
}
対象 解決方法については、
ハンドルの割り当て SQLAllocHandle 関数
ステートメント処理の取り消し SQLCancel 関数
カーソルを閉じる SQLCloseCursor 関数
ハンドルの解放 SQLFreeHandle 関数
カーソル名の設定 SQLSetCursorName 関数

参照

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