SQLFetchScroll--Recuperar conjunto de filas y devolver datos para todas las columnas enlazadas

Finalidad

Especificación: CLI de DB2 5.0 ODBC 3.0

SQLFetchScroll() recupera el conjunto especificado de filas de datos del conjunto resultante y devuelve datos para todas las columnas enlazadas. Los conjuntos de filas se pueden especificar en una posición absoluta o relativa.

Sintaxis 

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

Argumentos de la función

Tabla 50. Argumentos de SQLFetchScroll

Tipo de datos Argumento Uso Descripción
SQLHSTMT StatementHandle entrada Descriptor de contexto de sentencia
SQLSMALLINT FetchOrientation entrada Tipo de recuperación:
  • SQL_FETCH_NEXT
  • SQL_FETCH_PRIOR
  • SQL_FETCH_FIRST
  • SQL_FETCH_LAST
  • SQL_FETCH_ABSOLUTE
  • SQL_FETCH_RELATIVE
SQLINTEGER FetchOffset entrada Número de la fila para recuperar. La interpretación de este argumento depende del valor del argumento FetchOrientation.

Uso

SQLFetchScroll() devuelve un conjunto de filas especificado del conjunto resultante. Los conjuntos de filas se pueden especificar mediante una posición absoluta o relativa. SQLFetchScroll() se puede invocar sólo mientras exista un conjunto resultante, es decir después de que una llamada genere un conjunto resultante y antes de que se cierre el cursor para ese conjunto resultante. Si existe alguna columna enlazada, la función devuelve los datos de esas columnas. Si la aplicación ha especificado un puntero que apunta a una matriz de estado de filas o a un almacenamiento intermedio en el que devolver el número de filas recuperadas, SQLFetchScroll() devuelve también esta información. Las llamadas a SQLFetchScroll() se pueden intercalar con llamadas a SQLFetch().

Posicionamiento del cursor

Cuando se crea el conjunto resultante, el cursor está situado antes del comienzo del conjunto resultante. SQLFetchScroll() sitúa el cursor de bloques de acuerdo con los valores de los argumentos FetchOrientation y FetchOffset, tal y como se muestra en la lista siguiente. Las normas exactas para determinar el inicio del nuevo conjunto de filas se muestran en el apartado siguiente.

FetchOrientation
Significado

SQL_FETCH_NEXT
Devolver el conjunto de filas siguiente. Esto equivale a invocar SQLFetch(). SQLFetchScroll() no tiene en cuenta el valor de FetchOffset.

SQL_FETCH_PRIOR
Devolver el conjunto de filas anterior. SQLFetchScroll() no tiene en cuenta el valor de FetchOffset.

SQL_FETCH_RELATIVE
Devolver el conjunto de filas FetchOffset a partir del inicio del conjunto de filas actual.

SQL_FETCH_ABSOLUTE
Devolver el conjunto de filas que comienza en la fila FetchOffset.

SQL_FETCH_FIRST
Devolver el primer conjunto de filas del conjunto resultante. SQLFetchScroll() no tiene en cuenta el valor de FetchOffset.

SQL_FETCH_LAST
Devolver el último conjunto de filas completo del conjunto resultante. SQLFetchScroll() no tiene en cuenta el valor de FetchOffset.

El atributo de sentencia de SQL_ATTR_ROW_ARRAY_SIZE especifica el número de filas del conjunto de filas. Si el conjunto de filas que se recupera mediante SQLFetchScroll() se solapa con el final del conjunto resultante, SQLFetchScroll() devuelve un conjunto de filas parcial. Es decir, si S + R - 1 es mayor que L, siendo S la fila inicial del conjunto de filas que se recupera, R es el tamaño del conjunto de filas y L es la última fila del conjunto resultante, entonces sólo son válidas las primeras L - S + 1 filas del conjunto de filas. Las filas restantes están vacías y su estado es SQL_ROW_NOROW.

Una vez que SQLFetchScroll() vuelve, el cursor del conjunto de filas se sitúa en la primera fila del conjunto resultante.

Reglas del posicionamiento del cursor

Las secciones siguientes describen las reglas exactas para cada valor de FetchOrientation. Estas reglas utilizan la notación siguiente:

Antes del inicio
El cursor de bloques está situado antes del inicio del conjunto resultante. Si la primera fila del nuevo conjunto de filas está delante del inicio del conjunto resultante, SQLFetchScroll() devuelve SQL_NO_DATA.

Después del final
El cursor de bloques está situado después del final del conjunto resultante. Si la primera fila del nuevo conjunto de filas está detrás del final del conjunto resultante, SQLFetchScroll() devuelve SQL_NO_DATA.

CurrRowsetStart
Es el número de la primera fila del conjunto de filas actual.

LastResultRow
Es el número de la última fila del conjunto resultante.

RowsetSize
Es el tamaño del conjunto de filas.

FetchOffset
Es el valor del argumento FetchOffset.

Reglas para SQL_FETCH_NEXT


Tabla 51. Reglas para SQL_FETCH_NEXT:

Condición Primera fila del nuevo conjunto de filas
Antes del inicio 1
CurrRowsetStart + RowsetSize <= LastResultRow CurrRowsetStart + RowsetSize
CurrRowsetStart + RowsetSize > LastResultRow Después del final
Después del final Después del final

Reglas para SQL_FETCH_PRIOR


Tabla 52. Reglas para SQL_FETCH_PRIOR:

Condición Primera fila del nuevo conjunto de filas
Antes del inicio Antes del inicio
CurrRowsetStart = 1 Antes del inicio
1 < CurrRowsetStart <= RowsetSize 1a
CurrRowsetStart > RowsetSize CurrRowsetStart - RowsetSize
Después del final Y LastResultRow < RowsetSize 1a
Después del final Y LastResultRow >= RowsetSize LastResult - RowRowsetSize + 1

a
SQLFetchScroll() devuelve SQLSTATE 01S06 (Intento de recuperación antes de que el conjunto resultante devolviera el primer conjunto de filas) y SQL_SUCCESS_WITH_INFO.

Reglas para SQL_FETCH_RELATIVE


Tabla 53. Reglas para SQL_FETCH_RELATIVE:

Condición Primera fila del nuevo conjunto de filas
(Antes del inicio Y FetchOffset > 0) O BIEN (Después del final Y FetchOffset < 0) --a
Antes del inicio Y FetchOffset <= 0 Antes del inicio
CurrRowsetStart = 1 AND FetchOffset < 0 Antes del inicio
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset| > RowsetSize Antes del inicio
CurrRowsetStart > 1 Y CurrRowsetStart + FetchOffset < 1 Y |FetchOffset| <= RowsetSize 1b
1 <= CurrRowsetStart + FetchOffset <= LastResultRow CurrRowsetStart + FetchOffset
CurrRowsetStart + FetchOffset > LastResultRow Después del final
Después del final Y FetchOffset >= 0 Después del final

a
SQLFetchScroll() devuelve el mismo conjunto de filas que si se la llamara con FetchOrientation establecido en SQL_FETCH_ABSOLUTE. Para obtener más información, consulte la sección SQL_FETCH_ABSOLUTE.

b
SQLFetchScroll() devuelve SQLSTATE 01S06 (Intento de recuperación antes de que el conjunto resultante devolviera el primer conjunto de filas) y SQL_SUCCESS_WITH_INFO.

Reglas para SQL_FETCH_ABSOLUTE


Tabla 54. Reglas para SQL_FETCH_ABSOLUTE:

Condición Primera fila del nuevo conjunto de filas
FetchOffset < 0 Y |FetchOffset| <= LastResultRow LastResultRow + FetchOffset + 1
FetchOffset < 0 Y |FetchOffset| > LastResultRow Y |FetchOffset| > RowsetSize Antes del inicio
FetchOffset < 0 Y |FetchOffset | > LastResultRow Y |FetchOffset| <= RowsetSize 1a
FetchOffset = 0 Antes del inicio
1 <= FetchOffset <= LastResultRow FetchOffset
FetchOffset > LastResultRow Después del final

a
SQLFetchScroll() devuelve SQLSTATE 01S06 (Intento de recuperación antes de que el conjunto resultante devolviera el primer conjunto de filas) y SQL_SUCCESS_WITH_INFO.

Reglas para SQL_FETCH_FIRST:


Tabla 55. Reglas para SQL_FETCH_FIRST:

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

Reglas para SQL_FETCH_LAST


Tabla 56. Reglas para SQL_FETCH_LAST:

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

Devolución de datos de columnas enlazadas

SQLFetchScroll() devuelve datos de columnas enlazadas de la misma manera que SQLFetch(). Para obtener más información, consulte la sección SQLFetch--Recuperar la fila siguiente.

Si no existe ninguna columna enlazada, SQLFetchScroll() no devuelve datos, pero sitúa el cursor de bloques en la posición especificada. En este caso, y al igual que ocurre con SQLFetch(), puede utilizar SQLGetData() para recuperar la información.

Direcciones de almacenamientos intermedios

SQLFetchScroll() utiliza el mismo método que SQLFetch() para determinar la dirección de los almacenamientos intermedios de datos y de longitudes/indicadores. Para obtener más información, consulte el apartado SQLBindCol--Enlazar una columna a una variable de aplicación.

Matriz de estado de filas

La matriz de estado de filas se utiliza para devolver el estado de cada una de las filas del conjunto de filas. La dirección de esta matriz se especifica con el atributo de sentencia de SQL_ATTR_ROW_STATUS_PTR. La matriz es asignada por la aplicación y debe tener tantos elementos como especifique el atributo de sentencia de SQL_ATTR_ROW_ARRAY_SIZE. Sus valores son establecidos por SQLFetch() y SQLFetchScroll(). Si el valor del atributo de sentencia de SQL_ATTR_ROW_STATUS_PTR es un puntero nulo, estas funciones no devuelven el estado de las filas.

El contenido del almacenamiento intermedio de la matriz de estado de filas es indefinido si SQLFetch() o SQLFetchScroll() no devuelve SQL_SUCCESS ni SQL_SUCCESS_WITH_INFO.

La matriz de estado de filas devuelve los valores siguientes.

Valor de la matriz de estado de filas
Descripción

SQL_ROW_SUCCESS
La fila se recupera satisfactoriamente.

SQL_ROW_SUCCESS_WITH_INFO
La fila se recupera satisfactoriamente. No obstante, se devuelve un mensaje de aviso referente a la fila.

SQL_ROW_ERROR
Se produjo un error durante la recuperación de la fila.

SQL_ROW_NOROW
El conjunto de filas se solapó con el final del conjunto resultante y no se devolvió ninguna fila que corresponda a este elemento de la matriz de estado de filas.

Almacenamiento intermedio de filas recuperadas

El almacenamiento intermedio de filas recuperadas se utiliza para devolver el número de filas recuperadas, incluidas aquéllas para las que no se devolvió ningún dato debido a un error producido al recuperar las filas. Es el número de filas para las que el valor en la matriz de estado de filas no es SQL_ROW_NOROW. La dirección de este almacenamiento intermedio se especifica con el atributo de sentencia de SQL_ATTR_ROWS_FETCHED_PTR. El almacenamiento intermedio es asignado por la aplicación. Sus valores son establecidos por SQLFetch() y SQLFetchScroll(). Si el valor del atributo de sentencia de SQL_ATTR_ROWS_FETCHED_PTR es un puntero nulo, estas funciones no devuelven el número de filas recuperadas. Para determinar el número de la fila actual en el conjunto resultante, una aplicación puede invocar SQLGetStmtAttr() con el atributo SQL_ATTR_ROW_NUMBER.

El contenido del almacenamiento intermedio de filas recuperadas es indefinido si SQLFetch() o SQLFetchScroll() no devuelve SQL_SUCCESS ni SQL_SUCCESS_WITH_INFO, excepto cuando se devuelve SQL_NO_DATA, en cuyo caso el valor contenido en el almacenamiento intermedio de filas recuperadas se establece en 0.

Códigos de retorno

Diagnósticos

Tabla 57. SQLSTATE de SQLFetchScroll

SQLSTATE Descripción Explicación
01000 Aviso Mensaje informativo. (La función devuelve SQL_SUCCESS_WITH_INFO).
01004 Datos truncados. Los datos devueltos para una o más columnas están truncados. Los valores de tipo serie o los valores numéricos se truncan por la derecha. (Se devuelve SQL_SUCCESS_WITH_INFO si no se ha producido ningún error).
01S06 Se ha intentado recuperar antes de que el conjunto resultante devolviera el primer conjunto de filas. El conjunto de filas solicitado se solapó con el inicio del conjunto resultante cuando la posición actual estaba más allá de la primera fila, y FetchOrientation era SQL_PRIOR o bien FetchOrientation era SQL_RELATIVE con un desplazamiento (FetchOffset) negativo cuyo valor absoluto era menor o igual que el valor actual de SQL_ATTR_ROW_ARRAY_SIZE. (La función devuelve SQL_SUCCESS_WITH_INFO).
07006 Conversión no válida. Los datos no se pudieron convertir de forma adecuada al tipo de datos especificado por fCType en SQLBindCol().
22002 Almacenamiento intermedio de salida o de indicadores no valido. El valor de puntero especificado para el argumento pcbValue en SQLBindCol() es un puntero nulo y el valor de la columna correspondiente es nulo. No existe ninguna manera de notificar SQL_NULL_DATA.
22003 Valor numérico fuera de rango. La devolución del valor numérico para una o más columnas enlazadas hubiera provocado el truncamiento de la parte entera del número.
24000 Estado no válido del cursor. StatementHandle está en estado de ejecutado, pero no hay ningún conjunto resultante asociado al StatementHandle.
HY000 Error general. Se ha producido un error para el que no existe ningún SQLSTATE específico. El mensaje de error devuelto por SQLGetDiagRec() en el almacenamiento intermedio *MessageText describe el error y su causa.
HY001 Error de asignación de memoria. CLI de DB2 no puede asignar la memoria necesaria para ejecutar o finalizar la función.
HY010 Error de secuencia de función. Se llama a la función antes de llamar a SQLPrepare() o SQLExecDirect() para el descriptor de sentencia (StatementHandle).
HY106 Tipo de recuperación fuera de rango. El valor especificado para el argumento FetchOrientation no es válido.

El valor del atributo de sentencia de SQL_CURSOR_TYPE es SQL_CURSOR_FORWARD_ONLY y el valor del argumento FetchOrientation no es SQL_FETCH_NEXT.

HY107 Valor de fila fuera de rango. El valor especificado con el atributo de sentencia de SQL_ATTR_CURSOR_TYPE es SQL_CURSOR_KEYSET_DRIVEN, pero el valor especificado con el atributo de sentencia de SQL_ATTR_KEYSET_SIZE es mayor que 0 y menor que el valor especificado con el atributo de sentencia de SQL_ATTR_ROW_ARRAY_SIZE.

Restricciones

Ninguna.

Consulta relacionada