SQLFreeStmt 関数

[アーティクル]
05/23/2023

準拠
導入されたバージョン: 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 ヘッダーファイル

SQLFreeStmt 関数

構文

引数

戻り値

診断

説明

例

参照

フィードバック

フィードバック

その他のリソース

SQLFreeStmt 関数

構文

引数

戻り値

診断

説明

例

関連する関数

参照

フィードバック

フィードバック

その他のリソース