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.
Funciones relacionadas
| 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 |