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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC