Función SQLRowCount
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLRowCount devuelve el número de filas afectadas por una instrucción UPDATE, INSERT o DELETE ; una operación de SQL_ADD, SQL_UPDATE_BY_BOOKMARK o SQL_DELETE_BY_BOOKMARK en SQLBulkOperations; o una operación de SQL_UPDATE o SQL_DELETE en SQLSetPos.
Sintaxis
SQLRETURN SQLRowCount(
SQLHSTMT StatementHandle,
SQLLEN * RowCountPtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrucciones.
RowCountPtr
[Salida] Apunta a un búfer en el que se va a devolver un recuento de filas. Para las instrucciones UPDATE, INSERT y DELETE , para las operaciones de SQL_ADD, SQL_UPDATE_BY_BOOKMARK y SQL_DELETE_BY_BOOKMARK en SQLBulkOperations, y para las operaciones de SQL_UPDATE o SQL_DELETE en SQLSetPos, el valor devuelto en *RowCountPtr es el número de filas afectadas por la solicitud o -1 si el número de filas afectadas no está disponible.
Cuando se llama a SQLExecute, SQLExecDirect, SQLBulkOperations, SQLSetPos o SQLMoreResults , el campo SQL_DIAG_ROW_COUNT de la estructura de datos de diagnóstico se establece en el recuento de filas y el recuento de filas se almacena en caché de forma dependiente de la implementación. SQLRowCount devuelve el valor de recuento de filas almacenados en caché. El valor de recuento de filas almacenados en caché es válido hasta que el identificador de instrucción se vuelve a establecer en el estado preparado o asignado, se vuelve a ejecutar la instrucción o se llama a SQLCloseCursor . Tenga en cuenta que si se ha llamado a una función desde que se estableció el campo SQL_DIAG_ROW_COUNT, el valor devuelto por SQLRowCount podría ser diferente del valor del campo SQL_DIAG_ROW_COUNT porque el campo SQL_DIAG_ROW_COUNT se restablece a 0 por cualquier llamada de función.
Para otras instrucciones y funciones, el controlador puede definir el valor devuelto en *RowCountPtr. Por ejemplo, algunos orígenes de datos pueden devolver el número de filas devueltas por una instrucción SELECT o una función de catálogo antes de capturar las filas.
Nota:
Muchos orígenes de datos no pueden devolver el número de filas de un conjunto de resultados antes de capturarlos; para la interoperabilidad máxima, las aplicaciones no deben depender de este comportamiento.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLRowCount 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 SQLRowCount 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 funciones | (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 la función SQLRowCount . (DM) SQLExecute, SQLExecDirect o SQLMoreResults se llamó a para statementHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) Se llamó a la función antes de llamar a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para statementHandle. (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 el 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. |
| HY117 | La conexión se suspende debido al estado de transacción desconocido. Solo se permiten las funciones de desconexión y solo lectura. | (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran. |
| 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 respondiera 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
Si la última instrucción SQL ejecutada en el identificador de instrucción no era una instrucción UPDATE, INSERT o DELETE o si el argumento Operation de la llamada anterior a SQLBulkOperations no era SQL_ADD, SQL_UPDATE_BY_BOOKMARK o SQL_DELETE_BY_BOOKMARK, o si el argumento Operation de la llamada anterior a SQLSetPos no se SQL_UPDATE o SQL_DELETE, el valor de *RowCountPtr está definido por el controlador. Para obtener más información, vea Determinar el número de filas afectadas.
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Ejecución de una instrucción SQL | Función SQLExecDirect |
| Ejecución de una instrucción SQL preparada | Función SQLExecute |