Función SQLExtendedFetch
Conformidad
Versión introducida: Cumplimiento de estándares odbc 1.0: en desuso
Resumen
SQLExtendedFetch captura el conjunto de filas de datos especificado del conjunto de resultados y devuelve datos para todas las columnas enlazadas. Los conjuntos de filas se pueden especificar en una posición absoluta o relativa o por marcador.
Nota
En ODBC 3*.x*, SQLExtendedFetch se ha reemplazado por SQLFetchScroll. Las aplicaciones ODBC 3*.x* no deben llamar a SQLExtendedFetch; en su lugar, deben llamar a SQLFetchScroll. El Administrador de controladores asigna SQLFetchScroll a SQLExtendedFetch al trabajar con un controlador ODBC 2*.x*. Los controladores ODBC 3*.x* deben admitir SQLExtendedFetch si quieren trabajar con aplicaciones ODBC 2*.x* que lo llaman. Para obtener más información, vea "Comentarios" y cursores de bloque, cursores desplazables y compatibilidad con versiones anteriores en el apéndice G: Directrices para controladores para la compatibilidad con versiones anteriores.
Sintaxis
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Argumentos
StatementHandle
[Entrada] Identificador de instrucción.
FetchOrientation
[Entrada] Tipo de captura. Esto es lo mismo que FetchOrientation en SQLFetchScroll.
FetchOffset
[Entrada] Número de la fila que se va a capturar. Esto es lo mismo que FetchOffset en SQLFetchScroll, con una excepción. Cuando FetchOrientation es SQL_FETCH_BOOKMARK, FetchOffset es un marcador de longitud fija, no un desplazamiento de un marcador. En otras palabras, SQLExtendedFetch recupera el marcador de este argumento, no el atributo de instrucción SQL_ATTR_FETCH_BOOKMARK_PTR. No admite marcadores de longitud variable y no admite la captura de un conjunto de filas en un desplazamiento (distinto de 0) de un marcador.
RowCountPtr
[Salida] Puntero a un búfer en el que se va a devolver el número de filas capturadas realmente. Este búfer se usa de la misma manera que el búfer especificado por el atributo de instrucción SQL_ATTR_ROWS_FETCHED_PTR. SQLExtendedFetch solo usa este búfer. SQLFetch o SQLFetchScroll no lo usan.
RowStatusArray
[Salida] Puntero a una matriz en la que se va a devolver el estado de cada fila. Esta matriz se usa de la misma manera que la matriz especificada por el atributo de instrucción SQL_ATTR_ROW_STATUS_PTR.
Sin embargo, la dirección de esta matriz no se almacena en el campo SQL_DESC_STATUS_ARRAY_PTR del IRD. Además, SQLExtendedFetch solo usa esta matriz y SQLBulkOperations con una operación de SQL_ADD o SQLSetPos cuando se llama después de SQLExtendedFetch. SQLFetch o SQLFetchScroll no lo usan y SQLBulkOperations o SQLSetPos cuando se les llama después de SQLFetch o SQLFetchScroll. Tampoco se usa cuando se llama a SQLBulkOperations con una operación de SQL_ADD antes de llamar a cualquier función fetch. En otras palabras, solo se usa en el estado de instrucción S7. No se usa en los estados de instrucción S5 o S6. Para obtener más información, vea Transiciones de instrucción en el Apéndice B: Tablas de transición de estado ODBC.
Las aplicaciones deben proporcionar un puntero válido en el argumento RowStatusArray ; si no es así, el comportamiento de SQLExtendedFetch y el comportamiento de las llamadas a SQLBulkOperations o SQLSetPos después de que SQLExtendedFetch haya colocado un cursor no está definido.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLExtendedFetch devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLError. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLExtendedFetch 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 SQLGetDiagField se pueden llamar con un DiagIdentifier de SQL_DIAG_ROW_NUMBER para determinar la fila que contiene esa columna.
| 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 con el botón derecho. Si era un valor numérico, la parte fraccionarcional del número se truncaba. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S01 | Error en la fila | Error al capturar una o varias filas. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S06 | Intento de capturar antes de que el conjunto de resultados devuelva el primer conjunto de filas | El conjunto de filas solicitado superpuesto el inicio del conjunto de resultados cuando la posición actual estaba más allá de la primera fila y FetchOrientation se SQL_PRIOR o FetchOrientation se SQL_RELATIVE con un valor FetchOffset negativo cuyo valor absoluto era menor o igual que el SQL_ROWSET_SIZE actual. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S07 | Truncamiento fraccional | Los datos devueltos para una columna se truncaron. En el caso de los tipos de datos numéricos, la parte fraccionarcional del número se trunca. En el caso de los tipos de datos time, timestamp y interval que contienen un componente de hora, la parte fraccionarcional de la hora se trunca. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 07006 | Infracción de atributo de tipo de datos restringido | No se pudo convertir un valor de datos en el tipo de datos de C especificado por TargetType en SQLBindCol. |
| 07009 | Índice de descriptor no válido | La columna 0 estaba enlazada con SQLBindCol 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. |
| 22002 | Variable de indicador necesaria, pero no proporcionada | Los datos NULL se capturaron en una columna cuyo StrLen_or_IndPtr establecido por SQLBindCol era un puntero nulo. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 22003 | Valor numérico fuera del intervalo | Devolver el valor numérico (como numérico o cadena) para una o varias columnas habría provocado el truncamiento de toda la parte del número (en lugar de fracciones). (Function devuelve SQL_SUCCESS_WITH_INFO). Para obtener más información, vea Directrices para tipos de datos numéricos e intervalos 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. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 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. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 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 C 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 tipo C del intervalo C. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 22018 | Valor de carácter no válido para la especificación de conversión | 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 C enlazado. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 24000 | Estado de cursor no válido | StatementHandle estaba en un estado ejecutado, pero no se ha asociado ningún conjunto de resultados con StatementHandle. |
| 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 SQLError 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 y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en StatementHandle y, a continuación, se llamó a la función de nuevo en StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multiproceso. |
| HY010 | Error de secuencia de función | (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 SQLExtendedFetch . (DM) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para la instrucciónHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) La InstrucciónHandle especificada 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 de ejecución 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 la instrucciónHandle 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 SQLExtendedFetch para la instrucciónHandle después de llamar a SQLFetch o SQLFetchScroll y antes de llamar a SQLFreeStmt con la opción SQL_CLOSE. Se llamó a SQLBulkOperations para una instrucción antes de llamar a SQLFetch, SQLFetchScroll o SQLExtendedFetch y, a continuación, se llamó a SQLExtendedFetch 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 acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY106 | Capturar el tipo fuera del intervalo | (DM) El valor especificado para el argumento FetchOrientation no era válido. (Vea "Comments.") El argumento FetchOrientation se SQL_FETCH_BOOKMARK y el atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_OFF. El valor de la opción de instrucción SQL_CURSOR_TYPE se SQL_CURSOR_FORWARD_ONLY y el valor del argumento FetchOrientation no se SQL_FETCH_NEXT. El argumento FetchOrientation se SQL_FETCH_RESUME. |
| HY107 | Valor de fila fuera del intervalo | El valor especificado con la opción de instrucción SQL_CURSOR_TYPE se SQL_CURSOR_KEYSET_DRIVEN, pero el valor especificado con el atributo de instrucción SQL_KEYSET_SIZE era mayor que 0 y menor que el valor especificado con el atributo de instrucción SQL_ROWSET_SIZE. |
| HY111 | Valor de marcador no válido | El argumento FetchOrientation se SQL_FETCH_BOOKMARK y el marcador especificado en el argumento FetchOffset no era válido. |
| HY117 | La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de 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 el tipo de captura especificado. 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. Este error solo se aplica cuando el tipo de datos SQL de la columna se asignó a un tipo de datos SQL específico del controlador. |
| HYT00 | Tiempo de espera agotado | El período de tiempo de espera de la consulta expiró antes de que el origen de datos devolva el conjunto de resultados. El período de tiempo de espera se establece a través de SQLSetStmtOption, SQL_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 . |
Comentarios
El comportamiento de SQLExtendedFetch es idéntico al de SQLFetchScroll, con las excepciones siguientes:
SQLExtendedFetch y SQLFetchScroll usan métodos diferentes para devolver el número de filas capturadas. SQLExtendedFetch devuelve el número de filas capturadas en *RowCountPtr; SQLFetchScroll devuelve el número de filas capturadas directamente en el búfer al que apunta SQL_ATTR_ROWS_FETCHED_PTR. Para obtener más información, vea el argumento RowCountPtr .
SQLExtendedFetch y SQLFetchScroll devuelven el estado de cada fila en matrices diferentes. Para obtener más información, vea el argumento RowStatusArray .
SQLExtendedFetch y SQLFetchScroll usan métodos diferentes para recuperar el marcador cuando FetchOrientation se SQL_FETCH_BOOKMARK. SQLExtendedFetch no admite marcadores de longitud variable ni captura conjuntos de filas en un desplazamiento distinto de 0 de un marcador. Para obtener más información, vea el argumento FetchOffset .
SQLExtendedFetch y SQLFetchScroll usan diferentes tamaños de conjunto de filas. SQLExtendedFetch usa el valor del atributo de instrucción SQL_ROWSET_SIZE y SQLFetchScroll usa el valor del atributo de instrucción SQL_ATTR_ROW_ARRAY_SIZE.
SQLExtendedFetch tiene una semántica de control de errores ligeramente diferente que SQLFetchScroll. Para obtener más información, vea "Control de errores" en la sección "Comentarios" de SQLFetchScroll.
SQLExtendedFetch no admite desplazamientos de enlace (el atributo de instrucción SQL_ATTR_ROW_BIND_OFFSET_PTR).
Las llamadas a SQLExtendedFetch no se pueden mezclar con llamadas a SQLFetch o SQLFetchScroll, y si se llama a SQLBulkOperations antes de llamar a cualquier función fetch, NO se puede llamar a SQLExtendedFetch hasta que se cierre y vuelva a abrir el cursor. Es decir, se puede llamar a SQLExtendedFetch solo en el estado de instrucción S7. Para obtener más información, vea Transiciones de instrucción en el Apéndice B: Tablas de transición de estado ODBC.
Cuando una aplicación llama a SQLFetchScroll mientras usa un controlador ODBC 2*.x*, el Administrador de controladores asigna esta llamada a SQLExtendedFetch. Para obtener más información, vea "CONTROLADORES SQLFetchScroll y ODBC 2*.x* en SQLFetchScroll.
En ODBC 2*.x*, se llamó a SQLExtendedFetch para capturar varias filas y se llamó a SQLFetch para capturar una sola fila. En ODBC 3*.x*, por otro lado, se puede llamar a SQLFetch para capturar varias filas.
Funciones relacionadas
| Para información acerca de | Vea |
|---|---|
| Enlace de un búfer a una columna de un conjunto de resultados | SQLBindCol (función) |
| Realización de operaciones masivas de inserción, actualización o eliminación | Función SQLBulkOperations |
| Cancelación del procesamiento de instrucciones | Función SQLCancel |
| Devolver información sobre una columna de un conjunto de resultados | SQLDescribeCol (función) |
| Ejecución de una instrucción SQL | Función SQLExecDirect |
| Ejecución de una instrucción SQL preparada | Función SQLExecute |
| Devolver el número de columnas del conjunto de resultados | SQLNumResultCols (función) |
| Colocación del cursor, actualización de datos en el conjunto de filas o actualización o eliminación de datos en el conjunto de resultados | Función SQLSetPos |
| Establecimiento de un atributo de instrucción | Función SQLSetStmtAttr |