| Especificación: | CLI de DB2 1.1 | ODBC 1.0 |
|
SQLFetch() avanza el cursor hasta la siguiente fila del conjunto resultante y recupera las columnas enlazadas.
Las columnas pueden estar asignadas al almacenamiento de la aplicación.
Cuando se llama a SQLFetch(), se realiza la transferencia de datos apropiada, junto con la conversión de datos que se haya indicado al enlazar la columna. Las columnas también se pueden obtener individualmente después de la búsqueda, invocando SQLGetData().
SQLFetch() sólo se puede invocar después de generar un conjunto resultante (utilizando el mismo descriptor de sentencia) mediante la ejecución de una consulta.
Sintaxis
SQLRETURN SQLFetch (SQLHSTMT StatementHandle); /* hstmt */
Argumentos de la función
Tabla 48. Argumentos de SQLFetch
| Tipo de datos | Argumento | Uso | Descripción |
|---|---|---|---|
| SQLHSTMT | StatementHandle | entrada | Descriptor de contexto de sentencia. |
Uso
SQLFetch() sólo se puede invocar después de generar un conjunto resultante para el mismo descriptor de sentencia. Antes de invocar SQLFetch() por primera vez, el cursor se sitúa en el inicio del conjunto resultante.
El número de variables de aplicación enlazadas mediante SQLBindCol() no debe superar el número de columnas del conjunto resultante, de lo contrario SQLFetch() falla.
Si no se ha invocado SQLBindCol() para enlazar ninguna columna, SQLFetch() no devuelve ningún dato a la aplicación, sino que simplemente avanza el cursor. En este caso, se podría invocar SQLGetData() para obtener todas las columnas individualmente. Los datos de las columnas no enlazadas se descartan cuando SQLFetch() avanza el cursor hasta la fila siguiente.
Las columnas pueden estar asignadas al almacenamiento de la aplicación. Se utiliza SQLBindCol() para enlazar el almacenamiento de la aplicación a la columna. Durante la recuperación, se transfieren datos desde la base de datos a la aplicación. También se define la longitud de los datos disponibles para devolver.
Si el almacenamiento intermedio de enlace no es lo suficiente grande para albergar los datos devueltos por SQLFetch(), se truncan los datos. Si se truncan datos de tipo carácter, se devuelve SQL_SUCCESS_WITH_INFO, y se genera un estado SQL que informa del truncamiento. El argumento diferido de salida pcbValue de SQLBindCol() contiene la longitud real de los datos de columna recuperados del servidor. La aplicación debe comparar la longitud real de la salida con la longitud del almacenamiento intermedio de entrada (argumentos pcbValue y cbValueMax de SQLBindCol()) para determinar qué columnas de caracteres se truncaron.
El truncamiento de tipos de datos numéricos se notifica en forma de aviso si el truncamiento afecta a dígitos situados a la derecha de la coma decimal. Si el truncamiento se produce a la izquierda de la coma decimal, se devuelve un error (consulte la sección sobre diagnósticos).
Una vez recuperadas todas las filas del conjunto resultante, o cuando no sean necesarias las filas restantes, invoque SQLFreeStmt() para cerrar el cursor y rechazar los datos restantes y los recursos asociados.
DB2 Everyplace recupera una fila como máximo cada vez, en lugar de utilizar un conjunto de filas. DB2 Everyplace no da soporte a los descriptores de sentencias.
SQLFetch() determina si la aplicación ha especificado almacenamientos intermedios separados de longitudes y de indicadores. En este caso, si los datos no son nulos, SQLFetch() establece el almacenamiento intermedio de indicadores en 0 y devuelve la longitud en el almacenamiento intermedio de longitudes. Si los datos son nulos, SQLFetch() establece el almacenamiento intermedio de indicadores en SQL_NULL_DATA y no modifica el almacenamiento intermedio de longitudes.
Posicionamiento del cursor
Cuando se crea el conjunto resultante, el cursor está situado antes del comienzo del conjunto resultante. SQLFetch() recupera la fila siguiente.
Códigos de retorno
Se devuelve SQL_NO_DATA_FOUND si no hay ninguna fila en el conjunto resultante o si invocaciones anteriores de SQLFetch() han recuperado todas las filas del conjunto resultante.
Si se han recuperado todas las filas, el cursor está situado después del final del conjunto resultante.
Diagnósticos
Tabla 49. SQLSTATE de SQLFetch
| SQLSTATE | Descripción | Explicación |
|---|---|---|
| 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). |
| 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. |
| 58004 | Error inesperado del sistema. | Error no recuperable del sistema. |
| 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). |
| HY013 | Error inesperado de gestión de la memoria. | CLI de DB2 no puede acceder a la memoria necesaria para ejecutar o finalizar la función. |
Restricciones
Ninguna.
Consulta relacionada