Capturar una fila de datos
Para capturar una fila de datos, una aplicación llama a SQLFetch. Se puede llamar a SQLFetch con cualquier tipo de cursor, pero solo mueve el cursor del conjunto de filas en una dirección de solo avance. SQLFetch avanza el cursor a la siguiente fila y devuelve los datos de las columnas enlazadas con llamadas a SQLBindCol. Cuando el cursor llega al final del conjunto de resultados, SQLFetch devuelve SQL_NO_DATA. Para obtener ejemplos de llamadas a SQLFetch, consulte Uso de SQLBindCol.
Exactamente la forma en que se implementa SQLFetch es específica del controlador, pero el patrón general es que el controlador recupere los datos de las columnas enlazadas del origen de datos, los convierta según los tipos de las variables enlazadas y coloque los datos convertidos en esas variables. Si el controlador no puede convertir datos, SQLFetch devuelve un error. La aplicación puede seguir capturando filas, pero se pierden los datos de la fila actual. Lo que sucede con los datos de las columnas sin enlazar depende del controlador, pero la mayoría de los controladores los recuperan y descartan o nunca los recuperan.
El controlador también establece los valores de los búferes de longitud o indicador que se han enlazado. Si el valor de datos de una columna es NULL, el controlador establece el búfer de longitud o indicador correspondiente en SQL_NULL_DATA. Si el valor de los datos no es NULL, el controlador establece el búfer de longitud o indicador en la longitud de bytes de los datos después de la conversión. Si no se puede determinar esta longitud, como sucede en ocasiones con datos largos recuperados por más de una llamada de función, el controlador establece el búfer de longitud o indicador en SQL_NO_TOTAL. Para los tipos de datos de longitud fija, como enteros y estructuras de fecha, la longitud de bytes es el tamaño del tipo de datos.
Para los datos de longitud variable, como los datos binarios y de caracteres, el controlador comprueba la longitud de bytes de los datos convertidos con respecto a la longitud de bytes del búfer enlazado a la columna. La longitud del búfer se especifica en el argumento BufferLength en SQLBindCol. Si la longitud de bytes de los datos convertidos es mayor que la longitud de bytes del búfer, el controlador trunca los datos que caben en el búfer, devuelve la longitud no truncada en el búfer de longitud o indicador, devuelve SQL_SUCCESS_WITH_INFO y coloca SQLSTATE 01004 (truncado de datos) en los diagnósticos. La única excepción a esto es si se trunca un marcador de longitud variable cuando lo devuelve SQLFetch, que devuelve SQLSTATE 22001 (datos de cadena, truncado a la derecha).
Los datos de longitud fija nunca se truncan, ya que el controlador supone que el tamaño del búfer enlazado es el tamaño del tipo de datos. El truncamiento de datos tiende a ser poco frecuente, ya que la aplicación normalmente enlaza un búfer lo suficientemente grande como para contener todo el valor de datos. Determina el tamaño necesario de los metadatos. Sin embargo, la aplicación podría enlazar explícitamente un búfer que sabe que es demasiado pequeño. Por ejemplo, podría recuperar y mostrar los primeros 20 caracteres de una descripción de parte o los primeros 100 caracteres de una columna de texto largo.
El controlador debe terminar en NULL los datos de caracteres antes de que se devuelvan a la aplicación, incluso si se han truncado. El carácter de terminación NULL no se incluye en la longitud de bytes devuelta, pero requiere espacio en el búfer enlazado. Por ejemplo, supongamos que una aplicación usa cadenas compuestas de datos de caracteres en el juego de caracteres ASCII, un controlador tiene 50 caracteres de datos para devolver y el búfer de la aplicación tiene 25 bytes de longitud. En el búfer de la aplicación, el controlador devuelve los primeros 24 caracteres seguidos de un carácter de terminación NULL. En el búfer de longitud o indicador, devuelve una longitud de bytes de 50.
La aplicación puede restringir el número de filas del conjunto de resultados estableciendo el atributo de instrucción SQL_ATTR_MAX_ROWS antes de ejecutar la instrucción que crea el conjunto de resultados. Por ejemplo, el modo de vista previa de una aplicación que se usa para dar formato a los informes solo necesita suficientes datos para mostrar la primera página del informe. Al restringir el tamaño del conjunto de resultados, esta característica se ejecutaría más rápido. Este atributo de instrucción está diseñado para reducir el tráfico de red y podría no ser compatible con todos los controladores.