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.
| 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);
}
Funciones relacionadas
| 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 |