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 cómo se implementa SQLFetch es específico del controlador, pero el patrón general es para que el controlador recupere los datos de las columnas enlazadas del origen de datos, conviértalos 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 en absoluto.

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/indicador a la longitud en 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 para que quepan en el búfer, devuelve la longitud sin truncar 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 un marcador de longitud variable se trunca cuando SQLFetch devuelve SQLSTATE 22001 (cadena de texto truncada 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 larga.

Los datos de caracteres deben terminar en null por el controlador antes de que se devuelvan a la aplicación, incluso si se ha truncado. El carácter de terminación null no se incluye en la longitud de bytes devuelta, pero requiere espacio en el búfer asignado. 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/indicador, devuelve una longitud de 50 bytes.

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.