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 instrucción.

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 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 de SQL_DIAG_ROW_COUNT se restablece a 0 mediante 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 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 la función SQLRowCount . (DM) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para la instrucciónHandle 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 la instrucciónHandle 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 acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY117	La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de 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 se 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 ni 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 información acerca de	Vea
Ejecución de una instrucción SQL	Función SQLExecDirect
Ejecución de una instrucción SQL preparada	Función SQLExecute

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC