Función SQLFreeStmt

  • Artículo

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.

SQLSTATE Error Descripción
01000 Advertencia general Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
HY000 Error general Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa.
HY001 Error de asignación de memoria El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función.
HY010 Error de secuencia de función (DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a SQLFreeStmt .

(DM) SQLExecute, SQLExecDirect o SQLMoreResults se llamó a para statementHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función con Option establecido en SQL_RESET_PARAMS antes de recuperar los datos para todos los parámetros transmitidos.

(DM) Se llamó a una función de ejecución asincrónica para StatementHandle y todavía se estaba ejecutando cuando se llamó a esta función.

(DM) se llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para statementHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución.
HY013 Error de administración de memoria No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY092 Tipo de opción fuera del intervalo (DM) El valor especificado para el argumento Option no era:

SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS
HYT01 Se ha agotado el tiempo de espera de la conexión. El período de tiempo de espera de conexión expiró antes de que el origen de datos responda a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 El controlador no admite esta función (DM) El controlador asociado a StatementHandle no admite la función .

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);  
}
Para información acerca de Vea
Asignación de un identificador Función SQLAllocHandle
Cancelación del procesamiento de instrucciones Función SQLCancel
Cerrar un cursor Función SQLCloseCursor
Liberar un identificador Función SQLFreeHandle
Establecimiento de un nombre de cursor Función SQLSetCursorName

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC