SQLFetchScroll (biblioteca de cursores)
Importante
Esta característica se quitará en una versión futura de Windows. Evite usar esta característica en el nuevo trabajo de desarrollo y planee modificar las aplicaciones que actualmente usan esta característica. Microsoft recomienda usar la funcionalidad del cursor del controlador.
En este tema se describe el uso de la función SQLFetchScroll en la biblioteca de cursores. Para obtener información general sobre SQLFetchScroll, vea Función SQLFetchScroll.
La biblioteca de cursores implementa SQLFetchScroll llamando repetidamente a SQLFetch en el controlador. Transfiere los datos que recupera del controlador a los búferes de conjunto de filas proporcionados por la aplicación. También almacena en caché los datos en memoria y archivos de disco. Cuando una aplicación solicita un nuevo conjunto de filas, la biblioteca de cursores la recupera según sea necesario del controlador (si no se ha capturado previamente) o de la memoria caché (si se ha capturado previamente). Por último, la biblioteca de cursores mantiene el estado de los datos almacenados en caché y devuelve esta información a la aplicación en la matriz de estado de fila.
Cuando se usa la biblioteca de cursores, las llamadas a SQLFetchScroll no se pueden mezclar con llamadas a SQLFetch o SQLExtendedFetch.
Cuando se usa la biblioteca de cursores, se admiten las llamadas a SQLFetchScroll para ODBC 2. x y para ODBC 3. controladores x .
Búferes de conjuntos de filas
La biblioteca de cursores optimiza la transferencia de datos del controlador al búfer del conjunto de filas proporcionado por la aplicación si:
La aplicación usa el enlace de fila.
No hay bytes sin usar entre los campos de la estructura que la aplicación declara para contener una fila de datos.
Los campos en los que SQLFetch o SQLFetchScroll devuelven la longitud o indicador de una columna sigue el búfer de esa columna y precede al búfer de la columna siguiente. Estos campos son opcionales.
Cuando la aplicación solicita un nuevo conjunto de filas, la biblioteca de cursores recupera los datos de su memoria caché y del controlador según sea necesario. Si los conjuntos de filas nuevos y antiguos se superponen, la biblioteca de cursores puede optimizar su rendimiento reutilizando los datos de las secciones superpuestas de los búferes del conjunto de filas. Por lo tanto, los cambios no guardados en los búferes del conjunto de filas se pierden a menos que los conjuntos de filas nuevos y antiguos se superpongan y los cambios se encuentren en las secciones superpuestas de los búferes del conjunto de filas. Para guardar los cambios, una aplicación envía una instrucción de actualización posicionada.
Tenga en cuenta que la biblioteca de cursores siempre actualiza los búferes del conjunto de filas con datos de la memoria caché cuando una aplicación llama a SQLFetchScroll con el argumento FetchOrientation establecido en SQL_FETCH_RELATIVE y el argumento FetchOffset establecido en 0.
La biblioteca de cursores admite la llamada a SQLSetStmtAttr con un atributo de SQL_ATTR_ROW_ARRAY_SIZE para cambiar el tamaño del conjunto de filas mientras un cursor está abierto. El nuevo tamaño del conjunto de filas surtirá efecto la próxima vez que se llame a SQLFetchScroll .
Pertenencia a conjuntos de resultados
La biblioteca de cursores recupera datos del controlador solo cuando la aplicación la solicita. Según el origen de datos y la configuración del atributo de instrucción SQL_CONCURRENCY, esto tiene las siguientes consecuencias:
Los datos recuperados por la biblioteca de cursores pueden diferir de los datos que estaba disponibles en el momento en que se ejecutó la instrucción. Por ejemplo, después de abrir el cursor, algunos controladores pueden recuperar las filas insertadas en un punto más allá de la posición actual del cursor.
Los datos del conjunto de resultados podrían estar bloqueados por el origen de datos de la biblioteca de cursores y, por tanto, no estarán disponibles para otros usuarios.
Una vez que la biblioteca de cursores ha almacenado en caché una fila de datos, no puede detectar cambios en esa fila en el origen de datos subyacente (excepto para actualizaciones posicionadas y eliminaciones que funcionan en la memoria caché del mismo cursor). Esto ocurre porque, para las llamadas a SQLFetchScroll, la biblioteca de cursores nunca vuelve a capturar los datos del origen de datos. En su lugar, vuelve a capturar los datos de su caché.
Desplazarse
La biblioteca de cursores admite los siguientes tipos de captura en SQLFetchScroll.
| Tipo de cursor | Capturar tipos |
|---|---|
| Solo avance | SQL_FETCH_NEXT |
| estática | SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_RELATIVE SQL_FETCH_ABSOLUTE SQL_FETCH_BOOKMARK |
Errors
Cuando se llama a SQLFetchScroll y una de las llamadas a SQLFetch devuelve SQL_ERROR, la biblioteca de cursores continúa de la siguiente manera. Una vez completados estos pasos, la biblioteca de cursores continúa procesando.
Llama a SQLGetDiagRec para obtener información de error del controlador y lo publica como un registro de diagnóstico en el Administrador de controladores.
Establece el campo SQL_DIAG_ROW_NUMBER del registro de diagnóstico en el valor adecuado.
Establece el campo SQL_DIAG_COLUMN_NUMBER del registro de diagnóstico en el valor adecuado, si procede; de lo contrario, lo establece en 0.
Establece el valor de la fila en error en la matriz de estado de fila en SQL_ROW_ERROR.
Una vez que la biblioteca de cursores ha llamado a SQLFetch varias veces en su implementación de SQLFetchScroll, cualquier error o advertencia devuelto por una de las llamadas a SQLFetch estará en un registro de diagnóstico y se puede recuperar mediante una llamada a SQLGetDiagRec. Si los datos se truncaron cuando se capturaron, los datos truncados residirán ahora en la memoria caché de la biblioteca de cursores. Las llamadas posteriores a SQLFetchScroll para desplazarse a una fila con datos truncados devolverán los datos truncados y no se generará ninguna advertencia porque los datos se capturan de la memoria caché de la biblioteca de cursores. Para realizar un seguimiento de la longitud de los datos devueltos para que pueda determinar si los datos devueltos en un búfer se han truncado, una aplicación debe enlazar el búfer de longitud o indicador.
Operaciones de marcador
La biblioteca de cursores admite la llamada a SQLFetchScroll con una fetchOrientation de SQL_FETCH_BOOKMARK. También admite la especificación de un desplazamiento en el argumento FetchOffset que se puede usar en la operación de marcador. Esta es la única operación de marcador que admite la biblioteca de cursores. La biblioteca de cursores no admite llamar a SQLBulkOperations.
Si la aplicación ha establecido el atributo de instrucción SQL_ATTR_USE_BOOKMARKS y se ha enlazado a la columna marcador, la biblioteca de cursores genera un marcador de longitud fija y lo devuelve a la aplicación. La biblioteca de cursores crea y mantiene los marcadores que usa; no usa marcadores mantenidos en el origen de datos. Cuando se llama a SQLFetchScroll para recuperar un bloque de datos que ya se ha capturado desde el origen de datos, recupera los datos de la memoria caché de la biblioteca de cursores. Como resultado, el marcador usado en una llamada a SQLFetchScroll con una fetchOrientation de SQL_FETCH_BOOKMARK debe crearse y mantenerse mediante la biblioteca de cursores.
Interacción con otras funciones
Una aplicación debe llamar a SQLFetch o SQLFetchScroll antes de preparar o ejecutar las instrucciones update o delete posicionadas.