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されます。

説明

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);  
}  

関連する関数

参照

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