Función SQLFetch
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLFetch captura el siguiente conjunto de filas de datos del conjunto de resultados y devuelve datos para todas las columnas enlazadas.
Sintaxis
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Argumentos
StatementHandle
[Entrada] Identificador de instrucciones.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLFetch devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a la función 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 SQLFetch 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). |
| 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 SQLFetch y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle. A continuación, se llamó a la función SQLFetch de nuevo en StatementHandle. O bien, se llamó a la función SQLFetch y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multithread. |
| 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 SQLFetch . (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). |
| 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. |
| 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
SQLFetch devuelve el siguiente conjunto de filas del conjunto de resultados. Solo se puede llamar 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, SQLFetch también devuelve esta información. Las llamadas a SQLFetch se pueden mezclar con llamadas a SQLFetchScroll , pero no se pueden mezclar con llamadas a SQLExtendedFetch. Para obtener más información, vea Capturar una fila de datos.
Si una aplicación ODBC 3*.x* funciona con un controlador ODBC 2*.x*, el Administrador de controladores asigna llamadas SQLFetch a SQLExtendedFetch para un controlador ODBC 2*.x* que admita SQLExtendedFetch. Si el controlador ODBC 2*.x* no admite SQLExtendedFetch, el Administrador de controladores asigna llamadas SQLFetch a SQLFetch en el controlador ODBC 2*.x*, que solo puede capturar una sola fila.
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.
Colocación del cursor
Cuando se crea el conjunto de resultados, el cursor se coloca antes del inicio del conjunto de resultados. SQLFetch captura el siguiente conjunto de filas. Equivale a llamar a SQLFetchScroll con FetchOrientation establecido en SQL_FETCH_NEXT. Para obtener más información sobre los cursores, vea Cursores y cursores de bloque.
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 SQLFetch se superpone al final del conjunto de resultados, SQLFetch 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 SQLFetch vuelva, la fila actual es la primera fila del conjunto de filas.
Las reglas enumeradas en la tabla siguiente describen el posicionamiento del cursor después de una llamada a SQLFetch, en función de las condiciones enumeradas en la segunda tabla de esta sección.
| Condición | Primera fila del nuevo conjunto de filas |
|---|---|
| Antes de empezar | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Después de finalizar |
| Después de finalizar | Después de finalizar |
[1] Si el tamaño del conjunto de filas cambia entre capturas, este es el tamaño del conjunto de filas que se usó con la captura anterior.
[2] Si el tamaño del conjunto de filas cambia entre capturas, este es el tamaño del conjunto de filas que se usó con la nueva captura.
| 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, SQLFetch 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, SQLFetch 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. |
Por ejemplo, supongamos que un conjunto de resultados tiene 100 filas y el tamaño del conjunto de filas es 5. En la tabla siguiente se muestra el conjunto de filas y el código devuelto por SQLFetch para diferentes posiciones iniciales.
| Conjunto de filas actual | Código devuelto | Nuevo conjunto de filas | Número de filas capturadas |
|---|---|---|---|
| Antes de empezar | SQL_SUCCESS | De 1 a 5 | 5 |
| De 1 a 5 | SQL_SUCCESS | De 6 a 10 | 5 |
| De 52 a 56 | SQL_SUCCESS | De 57 a 61 | 5 |
| De 91 a 95 | SQL_SUCCESS | De 96 a 100 | 5 |
| De 93 a 97 | SQL_SUCCESS | De 98 a 100. Las filas 4 y 5 de la matriz de estado de fila se establecen en SQL_ROW_NOROW. | 3 |
| De 96 a 100 | SQL_NO_DATA | Ninguno. | 0 |
| De 99 a 100 | SQL_NO_DATA | Ninguno. | 0 |
| Después de finalizar | SQL_NO_DATA | Ninguno. | 0 |
Devolver datos en columnas enlazadas
Como SQLFetch devuelve cada fila, coloca los datos de cada columna enlazada en el búfer enlazado a esa columna. Si no hay columnas enlazadas, SQLFetch no devuelve datos, pero mueve el cursor de bloque hacia delante. Los datos todavía se pueden recuperar mediante SQLGetData. Si el cursor es un cursor multirow (es decir, el SQL_ATTR_ROW_ARRAY_SIZE es mayor que 1), se puede llamar a SQLGetData solo si se devuelve SQL_GD_BLOCK cuando se llama a SQLGetInfo con un InfoType de SQL_GETDATA_EXTENSIONS. (Para obtener más información, consulte SQLGetData.)
Para cada columna enlazada de una fila, SQLFetch hace lo siguiente:
Establece el búfer de longitud o indicador en SQL_NULL_DATA y continúa con la columna siguiente si los datos son NULL. Si los datos son NULL y no se ha enlazado ningún búfer de longitud o indicador, SQLFetch devuelve SQLSTATE 22002 (variable indicador requerida pero no proporcionada) para la fila y continúa con la fila siguiente. Para obtener información sobre cómo determinar la dirección del búfer de longitud o indicador, vea "Direcciones de búfer" en SQLBindCol.
Si los datos de la columna no son NULL, SQLFetch continúa con el paso 2.
Si el atributo de instrucción SQL_ATTR_MAX_LENGTH se establece en un valor distinto de cero y la columna contiene datos binarios o de caracteres, los datos se truncan en SQL_ATTR_MAX_LENGTH bytes.
Nota:
El atributo de instrucción SQL_ATTR_MAX_LENGTH está diseñado para reducir el tráfico de red. Por lo general, se implementa mediante el origen de datos, que trunca los datos antes de devolverlos a través de la red. Los controladores y los orígenes de datos no son necesarios para admitirlo. Por lo tanto, para garantizar que los datos se truncan en un tamaño determinado, una aplicación debe asignar un búfer de ese tamaño y especificar el tamaño en el argumento cbValueMax en SQLBindCol.
Convierte los datos en el tipo especificado por TargetType en SQLBindCol.
Si los datos se convierten en un tipo de datos de longitud variable, como caracteres o binarios, SQLFetch comprueba si la longitud de los datos supera la longitud del búfer de datos. Si la longitud de los datos de caracteres (incluido el carácter de terminación NULL) supera la longitud del búfer de datos, SQLFetch trunca los datos a la longitud del búfer de datos menos la longitud de un carácter de terminación null. A continuación, finaliza el valor NULL de los datos. Si la longitud de los datos binarios supera la longitud del búfer de datos, SQLFetch la trunca hasta la longitud del búfer de datos. La longitud del búfer de datos se especifica con BufferLength en SQLBindCol.
SQLFetch nunca trunca los datos convertidos en tipos de datos de longitud fija; siempre supone que la longitud del búfer de datos es el tamaño del tipo de datos.
Coloca los datos convertidos (y posiblemente truncados) en el búfer de datos. Para obtener información sobre cómo determinar la dirección del búfer de datos, vea "Direcciones de búfer" en SQLBindCol.
Coloca la longitud de los datos en el búfer de longitud o indicador. Si el puntero del indicador y el puntero de longitud se establecieron en el mismo búfer (como una llamada a SQLBindCol ), la longitud se escribe en el búfer para datos válidos y SQL_NULL_DATA se escribe en el búfer para los datos NULL. Si no se ha enlazado ningún búfer de longitud o indicador, SQLFetch no devuelve la longitud.
Para los datos binarios o de caracteres, esta es la longitud de los datos después de la conversión y antes del truncamiento debido a que el búfer de datos es demasiado pequeño. Si el controlador no puede determinar la longitud de los datos después de la conversión, como sucede en ocasiones con datos largos, establece la longitud en SQL_NO_TOTAL. Si los datos se truncaron debido al atributo de instrucción SQL_ATTR_MAX_LENGTH, el valor de este atributo se coloca en el búfer de longitud o indicador en lugar de la longitud real . Esto se debe a que este atributo está diseñado para truncar los datos en el servidor antes de la conversión, por lo que el controlador no tiene forma de averiguar cuál es la longitud real.
Para todos los demás tipos de datos, esta es la longitud de los datos después de la conversión; es decir, es el tamaño del tipo al que se convirtieron los datos.
Para obtener información sobre cómo determinar la dirección del búfer de longitud o indicador, vea "Direcciones de búfer" en SQLBindCol.
Si los datos se truncan durante la conversión sin pérdida de dígitos significativos (por ejemplo, el número real 1,234 se trunca al entero 1 cuando se convierte), SQLFetch devuelve SQLSTATE 01S07 (truncamiento fraccionario) y SQL_SUCCESS_WITH_INFO. Si los datos se truncan porque la longitud del búfer de datos es demasiado pequeña (por ejemplo, la cadena "abcdef" se coloca en un búfer de 4 bytes), SQLFetch devuelve SQLSTATE 01004 (truncado de datos) y SQL_SUCCESS_WITH_INFO. Si los datos se truncan debido al atributo de instrucción SQL_ATTR_MAX_LENGTH, SQLFetch devuelve SQL_SUCCESS y no devuelve SQLSTATE 01S07 (truncamiento fraccionario) o SQLSTATE 01004 (truncado de datos). Si los datos se truncan durante la conversión con una pérdida de dígitos significativos (por ejemplo, si un valor de SQL_INTEGER mayor que 100 000 se convirtieron en un SQL_C_TINYINT), SQLFetch devuelve SQLSTATE 22003 (valor numérico fuera del intervalo) y SQL_ERROR (si el tamaño del conjunto de filas es 1) o SQL_SUCCESS_WITH_INFO (si el tamaño del conjunto de filas es mayor que 1).
El contenido del búfer de datos enlazado y el búfer de longitud o indicador no están definidos si SQLFetch o SQLFetchScroll no devuelve SQL_SUCCESS ni SQL_SUCCESS_WITH_INFO.
Matriz de Estados de fila
La matriz de estado de fila se usa para devolver el estado de cada fila del conjunto de filas. La dirección de esta matriz se especifica con el atributo de instrucción SQL_ATTR_ROW_STATUS_PTR. La matriz se asigna mediante la aplicación y debe tener tantos elementos como se especifican en el atributo de instrucción SQL_ATTR_ROW_ARRAY_SIZE. Sus valores se establecen mediante SQLFetch, SQLFetchScroll y SQLBulkOperations o SQLSetPos (excepto cuando se les ha llamado después de que SQLExtendedFetch haya colocado el cursor). Si el valor del atributo de instrucción SQL_ATTR_ROW_STATUS_PTR es un puntero nulo, estas funciones no devuelven el estado de fila.
El contenido del búfer de matriz de estado de fila no está definido si SQLFetch o SQLFetchScroll no devuelve SQL_SUCCESS ni SQL_SUCCESS_WITH_INFO.
Los valores siguientes se devuelven en la matriz de estado de fila.
| Valor de matriz de estado de fila | Descripción |
|---|---|
| SQL_ROW_SUCCESS | La fila se capturó correctamente y no ha cambiado desde que se capturó por última vez desde este conjunto de resultados. |
| SQL_ROW_SUCCESS_WITH_INFO | La fila se capturó correctamente y no ha cambiado desde que se capturó por última vez desde este conjunto de resultados. Sin embargo, se devolvió una advertencia sobre la fila. |
| SQL_ROW_ERROR | Se ha producido un error al recuperar la fila. |
| SQL_ROW_UPDATED[1],[2], y [3] | La fila se capturó correctamente y ha cambiado desde que se capturó por última vez a partir de este conjunto de resultados. Si la fila se recupera de nuevo de este conjunto de resultados o se actualiza mediante SQLSetPos, el estado se cambia al nuevo estado de la fila. |
| SQL_ROW_DELETED[3] | La fila se ha eliminado desde que se capturó por última vez de este conjunto de resultados. |
| SQL_ROW_ADDED[4] | SQLBulkOperations insertó la fila. Si sqlSetPos vuelve a capturar la fila de este conjunto de resultados o actualiza su estado es SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | El conjunto de filas se superpone al final del conjunto de resultados y no se devolvió ninguna fila correspondiente a este elemento de la matriz de estado de fila. |
[1] En el caso de los cursores de conjunto de claves, mixtos y dinámicos, si se actualiza un valor de clave, se considera que se ha eliminado la fila de datos y se agrega una nueva fila.
[2] Algunos controladores no pueden detectar actualizaciones de datos y, por tanto, no pueden devolver este valor. Para determinar si un controlador puede detectar actualizaciones para las filas capturadas, una aplicación llama a SQLGetInfo con la opción SQL_ROW_UPDATES.
[3] SQLFetch solo puede devolver este valor cuando se mezcla con llamadas a SQLFetchScroll. Esto se debe a que SQLFetch avanza a través del conjunto de resultados y, cuando se usa exclusivamente, no vuelve a capturar ninguna fila. Dado que no se vuelven a capturar filas, SQLFetch no detecta los cambios realizados en las filas capturadas previamente. Sin embargo, si SQLFetchScroll coloca el cursor antes de las filas capturadas previamente y SQLFetch se usa para capturar esas filas, SQLFetch puede detectar cualquier cambio en esas filas.
[4] Solo devuelve SQLBulkOperations. No se establece mediante SQLFetch o SQLFetchScroll.
Búfer capturado de filas
El búfer capturado de filas se usa para devolver el número de filas capturadas, incluidas las filas para las que no se devolvió ningún dato porque se produjo un error mientras se capturaban. Es decir, es el número de filas para las que el valor de la matriz de estado de fila no es SQL_ROW_NOROW. La dirección de este búfer se especifica con el atributo de instrucción SQL_ATTR_ROWS_FETCHED_PTR. La aplicación asigna el búfer. Se establece mediante SQLFetch y SQLFetchScroll. Si el valor del atributo de instrucción SQL_ATTR_ROWS_FETCHED_PTR es un puntero nulo, estas funciones no devuelven el número de filas capturadas. Para determinar el número de la fila actual en el conjunto de resultados, una aplicación puede llamar a SQLGetStmtAttr con el atributo SQL_ATTR_ROW_NUMBER.
El contenido de las filas capturadas en el búfer no está definido si SQLFetch o SQLFetchScroll no devuelve SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, excepto cuando se devuelve SQL_NO_DATA, en cuyo caso el valor del búfer capturado de filas está establecido en 0.
Tratamiento de errores
Los errores y advertencias se pueden aplicar a filas individuales o a toda la función. Para obtener más información sobre los registros de diagnóstico, vea Diagnósticos y SQLGetDiagField.
Errores y advertencias en toda la función
Si se aplica un error a toda la función, como SQLSTATE HYT00 (tiempo de espera expirado) o SQLSTATE 24000 (estado de cursor no válido), SQLFetch devuelve SQL_ERROR y SQLSTATE aplicable. El contenido de los búferes del conjunto de filas no está definido y la posición del cursor no cambia.
Si se aplica una advertencia a toda la función, SQLFetch devuelve SQL_SUCCESS_WITH_INFO y sqlSTATE aplicable. Los registros de estado de las advertencias que se aplican a toda la función se devuelven antes de los registros de estado que se aplican a filas individuales.
Errores y advertencias en filas individuales
Si se produce un error (por ejemplo, SQLSTATE 22012 (división por cero) o una advertencia (como SQLSTATE 01004 (truncado de datos)) se aplica a una sola fila, SQLFetchhace lo siguiente:
Establece el elemento correspondiente de la matriz de estado de fila en SQL_ROW_ERROR para errores o SQL_ROW_SUCCESS_WITH_INFO para advertencias.
Agrega cero o más registros de estado que contienen SQLSTATEs para el error o la advertencia.
Establece los campos de número de fila y columna en los registros de estado. Si SQLFetch no puede determinar un número de fila o columna, establece ese número en SQL_ROW_NUMBER_UNKNOWN o SQL_COLUMN_NUMBER_UNKNOWN, respectivamente. Si el registro de estado no se aplica a una columna determinada, SQLFetch establece el número de columna en SQL_NO_COLUMN_NUMBER.
SQLFetch continúa capturando filas hasta que haya capturado todas las filas del conjunto de filas. Devuelve SQL_SUCCESS_WITH_INFO a menos que se produzca un error en cada fila del conjunto de filas (sin incluir filas con SQL_ROW_NOROW de estado), en cuyo caso devuelve SQL_ERROR. En concreto, si el tamaño del conjunto de filas es 1 y se produce un error en esa fila, SQLFetch devuelve SQL_ERROR.
SQLFetch devuelve los registros de estado en el orden de número de fila. Es decir, devuelve todos los registros de estado de las filas desconocidas (si existe); a continuación, devuelve todos los registros de estado de la primera fila (si existe) y, a continuación, devuelve todos los registros de estado de la segunda fila (si existe), etc. Los registros de estado de cada fila se ordenan según las reglas normales para ordenar los registros de estado; para obtener más información, vea "Secuencia de registros de estado" en SQLGetDiagField.
Descriptores y SQLFetch
En las secciones siguientes se describe cómo interactúa SQLFetch con los descriptores.
Asignaciones de argumentos
El controlador no establece ningún campo descriptor basado en los argumentos de SQLFetch.
Otros campos de descriptor
SQLFetch usa los siguientes campos descriptores.
| Campo descriptor | Desc. | Campo en | Establecer a través de |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | autorización | atributo de instrucción SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | autorización | atributo de instrucción SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | ARD | autorización | atributo de instrucción SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | ARD | autorización | atributo de instrucción SQL_ATTR_ROW_BIND_TYPE |
| SQL_DESC_COUNT | ARD | autorización | Argumento ColumnNumber de SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | records | Argumento TargetValuePtr de SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | records | argumento StrLen_or_IndPtr en SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | records | Argumento BufferLength en SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | records | argumento StrLen_or_IndPtr en SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | autorización | atributo de instrucción SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | ARD | records | Argumento TargetType en SQLBindCol |
Todos los campos descriptores también se pueden establecer mediante SQLSetDescField.
Separación de búferes de longitud e indicador
Las aplicaciones pueden enlazar un único búfer o dos búferes independientes que se pueden usar para contener valores de longitud e indicador. Cuando una aplicación llama a SQLBindCol, el controlador establece el SQL_DESC_OCTET_LENGTH_PTR y SQL_DESC_INDICATOR_PTR campos del ARD en la misma dirección, que se pasa en el argumento StrLen_or_IndPtr . Cuando una aplicación llama a SQLSetDescField o SQLSetDescRec, puede establecer estos dos campos en direcciones diferentes.
SQLFetch determina si la aplicación ha especificado búferes de indicador y longitud independientes. En este caso, cuando los datos no son NULL, SQLFetch establece el búfer de indicador en 0 y devuelve la longitud en el búfer de longitud. Cuando los datos son NULL, SQLFetch establece el búfer de indicador en SQL_NULL_DATA y no modifica el búfer de longitud.
Ejemplo de código
Consulte SQLBindCol, SQLColumns, SQLGetData y SQLProcedures.
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Enlazar un búfer a una columna de un conjunto de resultados | Función SQLBindCol |
| 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 un bloque de datos o desplazarse por un conjunto de resultados | Función SQLFetchScroll |
| Cierre del cursor en la instrucción | Función SQLFreeStmt |
| Capturar parte o toda una columna de datos | Función SQLGetData |
| Devolver el número de columnas del conjunto de resultados | Función SQLNumResultCols |
| Preparación de una instrucción para su ejecución | Función SQLPrepare |