Función SQLFreeStmt

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92

Resumen
SQLFreeStmt detiene el procesamiento asociado a una instrucción específica, cierra los cursores abiertos asociados a la instrucción, descarta los resultados pendientes o, opcionalmente, libera todos los recursos asociados al identificador de instrucción.

Sintaxis

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

Argumentos

StatementHandle
[Entrada] Identificador de instrucción

Opción
[Entrada] Una de las siguientes opciones:

SQL_ CLOSE: cierra el cursor asociado a StatementHandle (si se definió uno) y descarta todos los resultados pendientes. La aplicación puede volver a abrir este cursor más adelante ejecutando una instrucción SELECT con los mismos valores de parámetro o diferentes. Si no hay ningún cursor abierto, esta opción no tiene ningún efecto para la aplicación. También se puede llamar a SQLCloseCursor para cerrar un cursor. Para obtener más información, vea Cerrar el cursor.

SQL_DROP: esta opción está en desuso. Una llamada a SQLFreeStmt con una opción de SQL_DROP se asigna en el Administrador de controladores a SQLFreeHandle.

SQL_UNBIND: establece el campo SQL_DESC_COUNT del ARD en 0, liberando todos los búferes de columna enlazados por SQLBindCol para el statementHandle especificado. Esto no desenlace la columna de marcador; para ello, el campo SQL_DESC_DATA_PTR del ARD para la columna de marcador se establece en NULL. Observe que si esta operación se realiza en un descriptor asignado explícitamente compartido por más de una instrucción, la operación afectará a los enlaces de todas las instrucciones que comparten el descriptor. Para obtener más información, vea Información general sobre la recuperación de resultados (básico).

SQL_RESET_PARAMS: establece el campo SQL_DESC_COUNT del APD en 0, liberando todos los búferes de parámetros establecidos por SQLBindParameter para el statementHandle especificado. Si esta operación se realiza en un descriptor asignado explícitamente compartido por más de una instrucción, esta operación afectará a los enlaces de todas las instrucciones que comparten el descriptor. Para obtener más información, vea Parámetros de enlace.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLFreeStmt devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLFreeStmt y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Comentarios

Llamar a SQLFreeStmt con la opción SQL_CLOSE equivale a llamar a SQLCloseCursor, salvo que SQLFreeStmt con SQL_CLOSE no afecta a la aplicación si no hay ningún cursor abierto en la instrucción. Si no hay ningún cursor abierto, una llamada a SQLCloseCursor devuelve SQLSTATE 24000 (estado de cursor no válido).

Una aplicación no debe usar un identificador de instrucción después de liberarla; El Administrador de controladores no comprueba la validez de un identificador en una llamada de función.

Ejemplo

Es una buena práctica de programación liberar identificadores. Sin embargo, por motivos de simplicidad, el ejemplo siguiente no incluye código que libera los identificadores asignados. Para obtener un ejemplo de cómo liberar identificadores, vea Función 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);  
}  

Funciones relacionadas

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC