SQLFreeStmt 関数

適合 性
導入されたバージョン: ODBC 1.0 標準コンプライアンス: ISO 92

Summary
SQLFreeStmt は、特定の文に関連する処理を停止し、その文に関連付けられた開いているカーソルを閉じ、保留中の結果を破棄するか、または任意の文ハンドルに関連するすべてのリソースを解放します。

構文

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

引数

StatementHandle
[入力]文ハンドル

オプション
[入力]以下のいずれかの選択肢があります:

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

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

SQL_UNBIND:ARDのSQL_DESC_COUNTフィールドを0に設定し、与えられたStatementHandleに対してSQLBindColでバインドされたすべてのカラムバッファを解放します。 これでブックマーク欄のバインドが解除されるわけではありません。そのために、ARDのブックマーク列のSQL_DESC_DATA_PTRフィールドをNULLに設定します。 この操作が明示的に割り当てられたディスクリプタに対して実行され、複数の文で共有されている場合、その記述子を共有するすべての文のバインディングに影響が出ることに注意してください。 詳細については、「 検索結果の概要(基本)」をご覧ください。

SQL_RESET_PARAMS:APDのSQL_DESC_COUNTフィールドを0に設定し、SQLBindParameterが設定したすべてのパラメータバッファを解放します。 この操作が複数の文で共有される明示的に割り当てられたディスクリプタに対して行われる場合、この操作はディスクリプタを共有するすべての文の結合に影響を与えます。 詳細は「 バインディングパラメータ」を参照してください。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

Diagnostics

SQLFreeStmtがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返すと、SQLGetDiagRecをHandleTypeのSQL_HANDLE_STMTとStatementHandleのHandleで呼び出すことで、関連するSQLSTATE値を取得できます。 以下の表は 、SQLFreeStmt が通常返すSQLSTATE値を示し、それぞれをこの関数の文脈で説明しています。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

SQL_CLOSEオプションで SQLFreeStmt を呼び出すことは 、SQLCloseCursorを呼び出すのと同等ですが、SQL_CLOSEの SQLFreeStmt は文にカーソルが開いていなければアプリケーションに影響を与えません。 カーソルが開かれていない場合、 SQLCloseCursor への呼び出しでSQLSTATE 24000(無効カーソル状態)を返します。

アプリケーションは文ハンドルを解放された後に使用すべきではありません。ドライバーマネージャーは関数呼び出しでハンドルの有効性をチェックしません。

例

ハンドルを解放するのは良いプログラミングの実践です。 しかし、簡便化のため、以下のサンプルには割り当てられたハンドルを解放するコードは含まれていません。 ハンドルを解放する方法の例は 、SQLFreeHandle Functionを参照してください。

// 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 ヘッダー ファイル