SQLFreeStmt 関数

準拠
導入されたバージョン: ODBC 1.0 標準準拠: 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の HandleTypeStatementHandleハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLFreeStmt によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

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

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

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

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

SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を介して設定されます。
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 ヘッダー ファイル