Compartir vía


Función SQLFetchScroll

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.0: ISO 92

Resumen
SQLFetchScroll captura el conjunto de filas especificado de datos del conjunto de resultados y devuelve datos para todas las columnas enlazadas. Los conjuntos de filas se pueden especificar en una posición absoluta o relativa o en un marcador.

Al trabajar con un controlador ODBC 2.x, el Administrador de controladores asigna esta función a SQLExtendedFetch. Para obtener más información, vea Asignación de funciones de reemplazo para la compatibilidad con versiones anteriores de las aplicaciones.

Sintaxis

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);  

Argumentos

StatementHandle
[Entrada] Identificador de instrucciones.

FetchOrientation
[Entrada]

Tipo de captura:

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

Para obtener más información, vea "Colocar el cursor" en la sección "Comentarios".

FetchOffset
[Entrada]

Número de la fila que se va a capturar. La interpretación de este argumento depende del valor del argumento FetchOrientation . Para obtener más información, vea "Colocar el cursor" en la sección "Comentarios".

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLFetchScroll 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 SQLFetchScroll 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. Si se produce un error en una sola columna, se puede llamar a SQLGetDiagField con un DiagIdentifier de SQL_DIAG_COLUMN_NUMBER para determinar la columna en la que se produjo el error; y se puede llamar a SQLGetDiagField con un DiagIdentifier de SQL_DIAG_ROW_NUMBER para determinar la fila que contiene esa columna.

Para todos los SQLSTATE que pueden devolver SQL_SUCCESS_WITH_INFO o SQL_ERROR (excepto 01xxx SQLSTATEs), se devuelve SQL_SUCCESS_WITH_INFO si se produce un error en una o varias filas de una operación multirow y se devuelve SQL_ERROR si se produce un error en una operación de una sola fila.

SQLSTATE Error Descripción
01000 Advertencia general Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
01004 Datos de cadena, truncados a la derecha Los datos binarios o de cadena devueltos para una columna provocaron el truncamiento de datos binarios no nulos o caracteres no nulos. Si era un valor de cadena, se truncaba a la derecha.
01S01 Error en la fila Error al capturar una o varias filas.

(Si se devuelve este valor SQLSTATE cuando una aplicación ODBC 3*.x* funciona con un controlador ODBC 2*.x*, se puede omitir).
01S06 Intentar capturar antes de que el conjunto de resultados devuelva el primer conjunto de filas El conjunto de filas solicitado superpone el inicio del conjunto de resultados cuando FetchOrientation se SQL_FETCH_PRIOR, la posición actual estaba fuera de la primera fila y el número de la fila actual es menor o igual que el tamaño del conjunto de filas.

El conjunto de filas solicitado se superpone al inicio del conjunto de resultados cuando FetchOrientation se SQL_FETCH_PRIOR, la posición actual estaba más allá del final del conjunto de resultados y el tamaño del conjunto de filas era mayor que el tamaño del conjunto de resultados.

El conjunto de filas solicitado superpone el inicio del conjunto de resultados cuando FetchOrientation se SQL_FETCH_RELATIVE, FetchOffset era negativo y el valor absoluto de FetchOffset era menor o igual que el tamaño del conjunto de filas.

El conjunto de filas solicitado superpone el inicio del conjunto de resultados cuando FetchOrientation se SQL_FETCH_ABSOLUTE, FetchOffset era negativo y el valor absoluto de FetchOffset era mayor que el tamaño del conjunto de resultados, pero menor o igual que el tamaño del conjunto de filas.

(Function devuelve SQL_SUCCESS_WITH_INFO).
01S07 Truncamiento fraccionario Los datos devueltos para una columna se truncaron. Para los tipos de datos numéricos, la parte fraccionaria del número se ha truncado. En el caso de los tipos de datos time, timestamp y interval que contienen un componente de hora, se trunca la parte fraccionaria de la hora.

(Function devuelve SQL_SUCCESS_WITH_INFO).
07006 Infracción de atributo de tipo de datos restringido No se pudo convertir el valor de datos de una columna del conjunto de resultados en el tipo de datos especificado por TargetType en SQLBindCol.

La columna 0 estaba enlazada con un tipo de datos de SQL_C_BOOKMARK y el atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_VARIABLE.

La columna 0 estaba enlazada con un tipo de datos de SQL_C_VARBOOKMARK y el atributo de instrucción SQL_ATTR_USE_BOOKMARKS no se estableció en SQL_UB_VARIABLE.
07009 Índice de descriptor no válido El controlador era un controlador ODBC 2*.x* que no admite SQLExtendedFetch y un número de columna especificado en el enlace para una columna era 0.

La columna 0 estaba enlazada y el atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_OFF.
08S01 Error de vínculo de comunicación Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento.
22001 Datos de cadena, truncados a la derecha Se ha truncado un marcador de longitud variable devuelto para una columna.
22002 Variable de indicador necesaria pero no proporcionada Los datos NULL se capturaron en una columna cuyo StrLen_or_IndPtr establecido por SQLBindCol (o SQL_DESC_INDICATOR_PTR establecido por SQLSetDescField o SQLSetDescRec) era un puntero nulo.
22003 Valor numérico fuera del intervalo Devolver el valor numérico (como numérico o cadena) para una o varias columnas enlazadas habría provocado que toda la parte (en lugar de fraccionaria) del número se truncase.

Para obtener más información, vea Convertir datos de SQL a tipos de datos de C en el apéndice D: Tipos de datos.
22007 Formato datetime no válido Una columna de caracteres del conjunto de resultados estaba enlazada a una estructura C de fecha, hora o marca de tiempo, y un valor de la columna era, respectivamente, una fecha, hora o marca de tiempo no válidas.
22012 División por cero Se devolvió un valor de una expresión aritmética, lo que dio lugar a la división por cero.
22015 Desbordamiento de campo de intervalo La asignación de un tipo SQL numérico o de intervalo exacto a un tipo C de intervalo provocó una pérdida de dígitos significativos en el campo inicial.

Al capturar datos en un tipo de intervalo C, no había ninguna representación del valor del tipo SQL en el intervalo C.
22018 Valor de carácter no válido para la especificación de conversión Una columna de caracteres del conjunto de resultados estaba enlazada a un búfer de caracteres C y la columna contenía un carácter para el que no había ninguna representación en el juego de caracteres del búfer.

El tipo C era un numérico exacto o aproximado, una fecha y hora o un tipo de datos interval; el tipo SQL de la columna era un tipo de datos de caracteres; y el valor de la columna no era un literal válido del tipo de C enlazado.
24000 Estado de cursor no válido StatementHandle estaba en un estado ejecutado, pero ningún conjunto de resultados estaba asociado a StatementHandle.
40001 Error de serialización La transacción en la que se ejecutó la captura finalizó para evitar el interbloqueo.
40003 Finalización de instrucciones desconocida Error en la conexión asociada durante la ejecución de esta función y no se puede determinar el estado de la transacción.
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.
HY008 Operación cancelada El procesamiento asincrónico se ha habilitado para StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en StatementHandle. A continuación, se llamó a la función de nuevo en StatementHandle.

Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multiproceso.
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 SQLFetchScroll .

(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) El statementHandle especificado no estaba en estado ejecutado. Se llamó a la función sin llamar primero a SQLExecDirect, SQLExecute o una función de catálogo.

(DM) Se llamó a una función que ejecuta de forma asincrónica (no esta) 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.

(DM) SE llamó a SQLFetch para statementHandle después de llamar a SQLExtendedFetch y antes de llamar a SQLFreeStmt con la opción SQL_CLOSE.
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.
HY090 Longitud de búfer o cadena no válida El atributo de instrucción SQL_ATTR_USE_BOOKMARK se estableció en SQL_UB_VARIABLE y la columna 0 estaba enlazada a un búfer cuya longitud no era igual a la longitud máxima del marcador para este conjunto de resultados. (Esta longitud está disponible en el campo SQL_DESC_OCTET_LENGTH del IRD y se puede obtener llamando a .SQLDescribeCol, SQLColAttribute o SQLGetDescField).
HY106 Capturar el tipo fuera del intervalo DM) El valor especificado para el argumento FetchOrientation no era válido.

(DM) El argumento FetchOrientation se SQL_FETCH_BOOKMARK y el atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_OFF.

El valor del atributo de instrucción SQL_ATTR_CURSOR_TYPE se SQL_CURSOR_FORWARD_ONLY y el valor del argumento FetchOrientation no se SQL_FETCH_NEXT.

El valor del atributo de instrucción SQL_ATTR_CURSOR_SCROLLABLE se SQL_NONSCROLLABLE y el valor del argumento FetchOrientation no se SQL_FETCH_NEXT.
HY107 Valor de fila fuera del intervalo El valor especificado con el atributo de instrucción SQL_ATTR_CURSOR_TYPE se SQL_CURSOR_KEYSET_DRIVEN, pero el valor especificado con el atributo de instrucción SQL_ATTR_KEYSET_SIZE era mayor que 0 y menor que el valor especificado con el atributo de instrucción SQL_ATTR_ROW_ARRAY_SIZE.
HY111 Valor de marcador no válido El argumento FetchOrientation se SQL_FETCH_BOOKMARK y el marcador al que apunta el valor del atributo de instrucción SQL_ATTR_FETCH_BOOKMARK_PTR no era válido o era un puntero nulo.
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.
HYC00 Característica opcional no implementada El controlador o el origen de datos no admiten la conversión especificada por la combinación de TargetType en SQLBindCol y el tipo de datos SQL de la columna correspondiente.
HYT00 Se ha agotado el tiempo de espera El período de tiempo de espera de la consulta expiró antes de que el origen de datos devolviera el conjunto de resultados solicitado. El período de tiempo de espera se establece mediante SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
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 .
IM017 El sondeo está deshabilitado en modo de notificación asincrónica Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado.
IM018 No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador. Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación.

Comentarios

SQLFetchScroll devuelve un conjunto de filas especificado del conjunto de resultados. Los conjuntos de filas se pueden especificar por posición absoluta o relativa o por marcador. Solo se puede llamar a SQLFetchScroll mientras existe un conjunto de resultados, es decir, después de una llamada que crea un conjunto de resultados y antes de que se cierre el cursor sobre ese conjunto de resultados. Si hay alguna columna enlazada, devuelve los datos de esas columnas. Si la aplicación ha especificado un puntero a una matriz de estado de fila o un búfer en el que devolver el número de filas capturadas, SQLFetchScroll también devuelve esta información. Las llamadas a SQLFetchScroll se pueden mezclar con llamadas a SQLFetch , pero no se pueden mezclar con llamadas a SQLExtendedFetch.

Para obtener más información, vea Uso de cursores de bloque y uso de cursores desplazables.

Colocación del cursor

Cuando se crea el conjunto de resultados, el cursor se coloca antes del inicio del conjunto de resultados. SQLFetchScroll coloca el cursor de bloque en función de los valores de los argumentos FetchOrientation y FetchOffset , como se muestra en la tabla siguiente. Las reglas exactas para determinar el inicio del nuevo conjunto de filas se muestran en la sección siguiente.

FetchOrientation Significado
SQL_FETCH_NEXT Devuelve el siguiente conjunto de filas. Esto equivale a llamar a SQLFetch.

SQLFetchScroll omite el valor de FetchOffset.
SQL_FETCH_PRIOR Devuelve el conjunto de filas anterior.

SQLFetchScroll omite el valor de FetchOffset.
SQL_FETCH_RELATIVE Devuelve el conjunto de filas FetchOffset desde el principio del conjunto de filas actual.
SQL_FETCH_ABSOLUTE Devuelve el conjunto de filas a partir de la fila FetchOffset.
SQL_FETCH_FIRST Devuelve el primer conjunto de filas del conjunto de resultados.

SQLFetchScroll omite el valor de FetchOffset.
SQL_FETCH_LAST Devuelve el último conjunto de filas completo del conjunto de resultados.

SQLFetchScroll omite el valor de FetchOffset.
SQL_FETCH_BOOKMARK Devuelve las filas FetchOffset del conjunto de filas del marcador especificado por el atributo de instrucción SQL_ATTR_FETCH_BOOKMARK_PTR.

No es necesario que los controladores admitan todas las orientaciones de captura; Una aplicación llama a SQLGetInfo con un tipo de información de SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 o SQL_STATIC_CURSOR_ATTRIBUTES1 (según el tipo del cursor) para determinar qué orientaciones de captura son compatibles con el controlador. La aplicación debe examinar las máscaras de bits SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE y WQL_CA1_BOOKMARK en estos tipos de información. Además, si el cursor es de solo avance y FetchOrientation no es SQL_FETCH_NEXT, SQLFetchScroll devuelve SQLSTATE HY106 (tipo de captura fuera del intervalo).

El atributo de instrucción SQL_ATTR_ROW_ARRAY_SIZE especifica el número de filas del conjunto de filas. Si el conjunto de filas que captura SQLFetchScroll se superpone al final del conjunto de resultados, SQLFetchScroll devuelve un conjunto de filas parcial. Es decir, si S + R - 1 es mayor que L, donde S es la fila inicial del conjunto de filas que se captura, R es el tamaño del conjunto de filas y L es la última fila del conjunto de resultados, entonces solo las primeras filas L - S + 1 del conjunto de filas son válidas. Las filas restantes están vacías y tienen un estado de SQL_ROW_NOROW.

Después de que SQLFetchScroll vuelva, la fila actual es la primera fila del conjunto de filas.

Reglas de posicionamiento de cursores

En las secciones siguientes se describen las reglas exactas de cada valor de FetchOrientation. Estas reglas usan la notación siguiente.

Notación Significado
Antes de empezar El cursor de bloque se coloca antes del inicio del conjunto de resultados. Si la primera fila del nuevo conjunto de filas es anterior al inicio del conjunto de resultados, SQLFetchScroll devuelve SQL_NO_DATA.
Después de finalizar El cursor de bloque se coloca después del final del conjunto de resultados. Si la primera fila del nuevo conjunto de filas es después del final del conjunto de resultados, SQLFetchScroll devuelve SQL_NO_DATA.
CurrRowsetStart Número de la primera fila del conjunto de filas actual.
LastResultRow Número de la última fila del conjunto de resultados.
RowsetSize Tamaño del conjunto de filas.
FetchOffset Valor del argumento FetchOffset .
BookmarkRow Fila correspondiente al marcador especificado por el atributo de instrucción SQL_ATTR_FETCH_BOOKMARK_PTR.

SQL_FETCH_NEXT

Se aplican las reglas siguientes.

Condición Primera fila del nuevo conjunto de filas
Antes de empezar 1
CurrRowsetStart + RowsetSize[1] <= LastResultRow CurrRowsetStart + RowsetSize[1]
CurrRowsetStart + RowsetSize[1]> LastResultRow Después de finalizar
Después de finalizar Después de finalizar

[1] Si el tamaño del conjunto de filas ha cambiado desde la llamada anterior para capturar filas, este es el tamaño del conjunto de filas que se usó con la llamada anterior.

SQL_FETCH_PRIOR

Se aplican las reglas siguientes.

Condición Primera fila del nuevo conjunto de filas
Antes de empezar Antes de empezar
CurrRowsetStart = 1 Antes de empezar
1 < CurrRowsetStart <= RowsetSize [2] 1 [1]
CurrRowsetStart > RowsetSize [2] CurrRowsetStart - RowsetSize [2]
Después de finalizar AND LastResultRow < RowsetSize [2] 1 [1]
Después de finalizar AND LastResultRow >= RowsetSize [2] LastResultRow - RowsetSize + 1 [2]

[1] SQLFetchScroll devuelve SQLSTATE 01S06 (Intento de capturar antes de que el conjunto de resultados devuelva el primer conjunto de filas) y SQL_SUCCESS_WITH_INFO.

[2] Si el tamaño del conjunto de filas se ha cambiado desde la llamada anterior para capturar filas, este es el nuevo tamaño del conjunto de filas.

SQL_FETCH_RELATIVE

Se aplican las reglas siguientes.

Condición Primera fila del nuevo conjunto de filas
(Antes de iniciar AND FetchOffset > 0) O (después del final Y FetchOffset < 0) --[1]
BeforeStart AND FetchOffset <= 0 Antes de empezar
CurrRowsetStart = 1 AND FetchOffset < 0 Antes de empezar
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize [3] Antes de empezar
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize [3] 1 [2]
1 <= CurrRowsetStart + FetchOffset <= LastResultRow CurrRowsetStart + FetchOffset
CurrRowsetStart + FetchOffset > LastResultRow Después de finalizar
Después de finalizar AND FetchOffset >= 0 Después de finalizar

[1] SQLFetchScroll devuelve el mismo conjunto de filas que si se llamó con FetchOrientation establecido en SQL_FETCH_ABSOLUTE. Para obtener más información, consulte la sección "SQL_FETCH_ABSOLUTE".

[2] SQLFetchScroll devuelve SQLSTATE 01S06 (Intento de capturar antes de que el conjunto de resultados devuelva el primer conjunto de filas) y SQL_SUCCESS_WITH_INFO.

[3] Si el tamaño del conjunto de filas ha cambiado desde la llamada anterior para capturar filas, este es el nuevo tamaño del conjunto de filas.

SQL_FETCH_ABSOLUTE

Se aplican las reglas siguientes.

Condición Primera fila del nuevo conjunto de filas
FetchOffset < 0 AND | FetchOffset | <= LastResultRow LastResultRow + FetchOffset + 1
FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize [2] Antes de empezar
FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize [2] 1 [1]
FetchOffset = 0 Antes de empezar
1 <= FetchOffset <= LastResultRow FetchOffset
FetchOffset > LastResultRow Después de finalizar

[1] SQLFetchScroll devuelve SQLSTATE 01S06 (Intento de capturar antes de que el conjunto de resultados devuelva el primer conjunto de filas) y SQL_SUCCESS_WITH_INFO.

[2] Si el tamaño del conjunto de filas se ha cambiado desde la llamada anterior para capturar filas, este es el nuevo tamaño del conjunto de filas.

Una captura absoluta realizada en un cursor dinámico no puede proporcionar el resultado necesario porque las posiciones de fila de un cursor dinámico no están determinadas. Esta operación es equivalente a una captura seguida primero de una captura relativa; no es una operación atómica, como es una captura absoluta en un cursor estático.

SQL_FETCH_FIRST

Se aplican las reglas siguientes.

Condición Primera fila del nuevo conjunto de filas
Cualquiera 1

SQL_FETCH_LAST

Se aplican las reglas siguientes.

Condición Primera fila del nuevo conjunto de filas
RowsetSize [1]<= LastResultRow LastResultRow - RowsetSize + 1 [1]
RowsetSize [1]> LastResultRow 1

[1] Si el tamaño del conjunto de filas se ha cambiado desde la llamada anterior para capturar filas, este es el nuevo tamaño del conjunto de filas.

SQL_FETCH_BOOKMARK

Se aplican las reglas siguientes.

Condición Primera fila del nuevo conjunto de filas
BookmarkRow + FetchOffset < 1 Antes de empezar
1 <= BookmarkRow + FetchOffset <= LastResultRow BookmarkRow + FetchOffset
BookmarkRow + FetchOffset > LastResultRow Después de finalizar

Para obtener información sobre los marcadores, vea Bookmarks (ODBC) (Marcadores [ODBC]).

Efecto de las filas eliminadas, agregadas y de error en el movimiento del cursor

Los cursores estáticos y controlados por conjuntos de claves a veces detectan filas agregadas al conjunto de resultados y quitan filas eliminadas del conjunto de resultados. Al llamar a SQLGetInfo con las opciones de SQL_STATIC_CURSOR_ATTRIBUTES2 y SQL_KEYSET_CURSOR_ATTRIBUTES2 y examinar los SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS y SQL_CA2_SENSITIVITY_UPDATES máscaras de bits, una aplicación determina si los cursores implementados por un controlador determinado lo hacen. En el caso de los controladores que pueden detectar filas eliminadas y quitarlas, los párrafos siguientes describen los efectos de este comportamiento. En el caso de los controladores que pueden detectar filas eliminadas, pero no pueden quitarlas, las eliminaciones no tienen ningún efecto en los movimientos del cursor y los párrafos siguientes no se aplican.

Si el cursor detecta filas agregadas al conjunto de resultados o quita las filas eliminadas del conjunto de resultados, aparece como si detecta estos cambios solo cuando captura datos. Esto incluye el caso cuando se llama a SQLFetchScroll con FetchOrientation establecido en SQL_FETCH_RELATIVE y FetchOffset establecido en 0 para volver a capturar el mismo conjunto de filas, pero no incluye el caso cuando se llama a SQLSetPos con fOption establecido en SQL_REFRESH. En este último caso, los datos de los búferes del conjunto de filas se actualizan, pero no se vuelven a capturar y las filas eliminadas no se quitan del conjunto de resultados. Por lo tanto, cuando se elimina o se inserta una fila en el conjunto de filas actual, el cursor no modifica los búferes del conjunto de filas. En su lugar, detecta el cambio cuando captura cualquier conjunto de filas que haya incluido previamente la fila eliminada o ahora incluya la fila insertada.

Por ejemplo:

// Fetch the next rowset.  
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);  
// Delete third row of the rowset. Does not modify the rowset buffers.  
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);  
// The third row has a status of SQL_ROW_DELETED after this call.  
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);  
// Refetch the same rowset. The third row is removed, replaced by what  
// was previously the fourth row.  
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);  

Cuando SQLFetchScroll devuelve un nuevo conjunto de filas que tiene una posición relativa al conjunto de filas actual ( es decir, FetchOrientation se SQL_FETCH_NEXT, SQL_FETCH_PRIOR o SQL_FETCH_RELATIVE), no incluye cambios en el conjunto de filas actual al calcular la posición inicial del nuevo conjunto de filas. Sin embargo, incluye cambios fuera del conjunto de filas actual si es capaz de detectarlos. Además, cuando SQLFetchScroll devuelve un nuevo conjunto de filas que tiene una posición independiente del conjunto de filas actual, es decir, FetchOrientation es SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE o SQL_FETCH_BOOKMARK, incluye todos los cambios que puede detectar, incluso si están en el conjunto de filas actual.

Al determinar si las filas recién agregadas están dentro o fuera del conjunto de filas actual, se considera que un conjunto de filas parcial finaliza en la última fila válida; es decir, la última fila para la que el estado de la fila no es SQL_ROW_NOROW. Por ejemplo, supongamos que el cursor es capaz de detectar filas recién agregadas, el conjunto de filas actual es un conjunto de filas parcial, la aplicación agrega nuevas filas y el cursor agrega estas filas al final del conjunto de resultados. Si la aplicación llama a SQLFetchScroll con FetchOrientation establecida en SQL_FETCH_NEXT, SQLFetchScroll devuelve el conjunto de filas a partir de la primera fila recién agregada.

Por ejemplo, supongamos que el conjunto de filas actual comprende las filas de 21 a 30, el tamaño del conjunto de filas es 10, el cursor quita las filas eliminadas del conjunto de resultados y el cursor detecta las filas agregadas al conjunto de resultados. En la tabla siguiente se muestran las filas que SQLFetchScroll devuelve en varias situaciones.

Cambio Tipo de captura FetchOffset Nuevo conjunto de filas[1]
Eliminar fila 21 SIGUIENTE 0 De 31 a 40
Eliminar fila 31 SIGUIENTE 0 De 32 a 41
Insertar fila entre las filas 21 y 22 SIGUIENTE 0 De 31 a 40
Insertar fila entre las filas 30 y 31 SIGUIENTE 0 Fila insertada, de 31 a 39
Eliminar fila 21 PRIOR 0 De 11 a 20
Eliminar fila 20 PRIOR 0 De 10 a 19
Insertar fila entre las filas 21 y 22 PRIOR 0 De 11 a 20
Insertar fila entre las filas 20 y 21 PRIOR 0 De 12 a 20, fila insertada
Eliminar fila 21 RELATIVE 0 De 22 a 31[2]
Eliminar fila 21 RELATIVE 1 De 22 a 31
Insertar fila entre las filas 21 y 22 RELATIVE 0 21, fila insertada, de 22 a 29
Insertar fila entre las filas 21 y 22 RELATIVE 1 De 22 a 31
Eliminar fila 21 ABSOLUTE 21 De 22 a 31[2]
Eliminar fila 22 ABSOLUTE 21 De 21 a 23 a 31
Insertar fila entre las filas 21 y 22 ABSOLUTE 22 Fila insertada, de 22 a 29

[1] Esta columna usa los números de fila antes de insertar o eliminar las filas.

[2] En este caso, el cursor intenta devolver filas a partir de la fila 21. Dado que se ha eliminado la fila 21, la primera fila que devuelve es la fila 22.

Las filas de error (es decir, las filas con un estado de SQL_ROW_ERROR) no afectan al movimiento del cursor. Por ejemplo, si el conjunto de filas actual comienza con la fila 11 y el estado de la fila 11 es SQL_ROW_ERROR, al llamar a SQLFetchScroll con FetchOrientation establecido en SQL_FETCH_RELATIVE y FetchOffset establecido en 5, devuelve el conjunto de filas a partir de la fila 16, como lo haría si el estado de la fila 11 se SQL_SUCCESS.

Devolver datos en columnas enlazadas

SQLFetchScroll devuelve datos en columnas enlazadas de la misma manera que SQLFetch. Para obtener más información, vea "Devolver datos en columnas enlazadas" en la función SQLFetch.

Si no hay columnas enlazadas, SQLFetchScroll no devuelve datos, pero mueve el cursor de bloque a la posición especificada. Si los datos se pueden recuperar de columnas sin enlazar de un cursor de bloque con SQLGetData depende del controlador. Esta funcionalidad se admite si una llamada a SQLGetInfo devuelve el bit de SQL_GD_BLOCK para el tipo de información de SQL_GETDATA_EXTENSIONS.

Direcciones de búfer

SQLFetchScroll usa la misma fórmula para determinar la dirección de los búferes de datos y longitud o indicador que SQLFetch. Para obtener más información, vea "Direcciones de búfer" en la función SQLBindCol.

Matriz de Estados de fila

SQLFetchScroll establece los valores de la matriz de estado de fila de la misma manera que SQLFetch. Para obtener más información, vea "Matriz de estado de fila" en la función SQLFetch.

Búfer capturado de filas

SQLFetchScroll devuelve el número de filas capturadas en el búfer capturado de las filas de la misma manera que SQLFetch. Para obtener más información, vea "Búfer capturado de filas" en la función SQLFetch.

Tratamiento de errores

Cuando una aplicación llama a SQLFetchScroll en un controlador ODBC 3.x, el Administrador de controladores llama a SQLFetchScroll en el controlador. Cuando una aplicación llama a SQLFetchScroll en un controlador ODBC 2.x, el Administrador de controladores llama a SQLExtendedFetch en el controlador. Dado que SQLFetchScroll y SQLExtendedFetch controlan errores de una manera ligeramente diferente, la aplicación ve un comportamiento de error ligeramente diferente cuando llama a SQLFetchScroll en controladores ODBC 2.x y ODBC 3.x.

SQLFetchScroll devuelve errores y advertencias de la misma manera que SQLFetch; para obtener más información, vea "Control de errores" en SQLFetch. SQLExtendedFetch devuelve errores de la misma manera que SQLFetch, con las siguientes excepciones:

Cuando se produce una advertencia que se aplica a una fila determinada del conjunto de filas, SQLExtendedFetch establece la entrada correspondiente en la matriz de estado de fila en SQL_ROW_SUCCESS, no SQL_ROW_SUCCESS_WITH_INFO.

Si se producen errores en todas las filas del conjunto de filas, SQLExtendedFetch devuelve SQL_SUCCESS_WITH_INFO, no SQL_ERROR.

En cada grupo de registros de estado que se aplica a una fila individual, el primer registro de estado devuelto por SQLExtendedFetch debe contener SQLSTATE 01S01 (error en la fila); SQLFetchScroll no devuelve este valor SQLSTATE. Si SQLExtendedFetch no puede devolver SQLSTATEs adicionales, debe devolver esta instrucción SQLSTATE.

SQLFetchScroll y simultaneidad optimista

Si un cursor usa simultaneidad optimista( es decir, el atributo de instrucción SQL_ATTR_CONCURRENCY tiene un valor de SQL_CONCUR_VALUES o SQL_CONCUR_ROWVER - SQLFetchScroll actualiza los valores de simultaneidad optimistas utilizados por el origen de datos para detectar si una fila ha cambiado. Esto sucede siempre que SQLFetchScroll captura un nuevo conjunto de filas, incluido cuando vuelve a capturar el conjunto de filas actual. (Se llama con FetchOrientation establecido en SQL_FETCH_RELATIVE y FetchOffset establecido en 0).

Controladores SQLFetchScroll y ODBC 2.x

Cuando una aplicación llama a SQLFetchScroll en un controlador ODBC 2.x, el Administrador de controladores asigna esta llamada a SQLExtendedFetch. Pasa los siguientes valores para los argumentos de SQLExtendedFetch.

Argumento SQLExtendedFetch Valor
StatementHandle StatementHandle en SQLFetchScroll.
FetchOrientation FetchOrientation en SQLFetchScroll.
FetchOffset Si FetchOrientation no es SQL_FETCH_BOOKMARK, se usa el valor del argumento FetchOffset en SQLFetchScroll .

Si FetchOrientation es SQL_FETCH_BOOKMARK, se usa el valor almacenado en la dirección especificada por el atributo de instrucción SQL_ATTR_FETCH_BOOKMARK_PTR.
RowCountPtr Dirección especificada por el atributo de instrucción SQL_ATTR_ROWS_FETCHED_PTR.
RowStatusArray Dirección especificada por el atributo de instrucción SQL_ATTR_ROW_STATUS_PTR.

Para obtener más información, vea Bloquear cursores, cursores desplazables y compatibilidad con versiones anteriores en el apéndice G: Directrices del controlador para la compatibilidad con versiones anteriores.

Descriptores y SQLFetchScroll

SQLFetchScroll interactúa con descriptores de la misma manera que SQLFetch. Para obtener más información, vea la sección "Descriptores y SQLFetchScroll" de la función SQLFetch.

Ejemplo de código

Consulte Enlace de columnas, enlace de fila, instrucciones update y delete posicionadas y actualización de filas en el conjunto de filas con SQLSetPos.

Para obtener información sobre Vea
Enlazar un búfer a una columna de un conjunto de resultados Función SQLBindCol
Realización de operaciones masivas de inserción, actualización o eliminación Función SQLBulkOperations
Cancelación del procesamiento de instrucciones Función SQLCancel
Devolver información sobre una columna en un conjunto de resultados Función SQLDescribeCol
Ejecución de una instrucción SQL Función SQLExecDirect
Ejecución de una instrucción SQL preparada Función SQLExecute
Capturar una sola fila o un bloque de datos en una dirección de solo avance Función SQLFetch
Cierre del cursor en la instrucción Función SQLFreeStmt
Devolver el número de columnas del conjunto de resultados Función SQLNumResultCols
Colocación del cursor, actualización de datos en el conjunto de filas o actualización o eliminación de datos en el conjunto de resultados Función SQLSetPos
Establecimiento de un atributo de instrucción Función SQLSetStmtAttr

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC