Compartir a través de

SQLMoreResults (función)

  • Artículo

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ODBC

Resumen
SQLMoreResults determina si hay más resultados disponibles en una instrucción que contiene instrucciones SELECT, UPDATE, INSERT o DELETE y, si es así, inicializa el procesamiento de esos resultados.

Sintaxis

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);

Argumentos

StatementHandle
[Entrada] Identificador de instrucción.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE O SQL_PARAM_DATA_AVAILABLE.

Diagnóstico

Cuando SQLMoreResults devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado mediante una llamada a 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 SQLMoreResults 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.

SQLSTATE Error Descripción
01000 Advertencia general Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
01S02 El valor de la opción ha cambiado El valor de un atributo de instrucción cambió a medida que se procesaba el lote. (Function devuelve SQL_SUCCESS_WITH_INFO).
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.
40001 Error de serialización La transacción se revierte debido a un interbloqueo de recursos con otra transacción.
40003 Finalización de instrucciones desconocida No se pudo determinar la conexión asociada durante la ejecución de esta función y 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 SQLMoreResults y, antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en StatementHandle. A continuación, se llamó de nuevo a la función SQLMoreResults en StatementHandle.

Se llamó a la función SQLMoreResults 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 SQLMoreResults .

(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 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.
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.
HY117 La conexión se suspende debido al 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.
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 responda 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 posprocesamiento y completar la operación.

Comentarios

Las instrucciones SELECT devuelven conjuntos de resultados. Las instrucciones UPDATE, INSERT y DELETE devuelven un recuento de filas afectadas. Si alguna de estas instrucciones se procesan por lotes, se envían con matrices de parámetros (numeradas en orden de parámetros crecientes, en el orden en que aparecen en el lote), o en procedimientos, pueden devolver varios conjuntos de resultados o recuentos de filas. Para obtener información sobre lotes de instrucciones y matrices de parámetros, vea Lotes de instrucciones SQL y matrices de valores de parámetros.

Después de ejecutar el lote, la aplicación se coloca en el primer conjunto de resultados. La aplicación puede llamar a SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos y todas las funciones de metadatos, en el primer o cualquier conjunto de resultados posterior, como lo haría si hubiera un único conjunto de resultados. Una vez hecho con el primer conjunto de resultados, la aplicación llama a SQLMoreResults para pasar al siguiente conjunto de resultados. Si hay otro conjunto de resultados o recuento disponible, SQLMoreResults devuelve SQL_SUCCESS e inicializa el conjunto de resultados o el recuento para el procesamiento adicional. Si las instrucciones que generan recuento de filas aparecen entre instrucciones de generación de conjuntos de resultados, se pueden superar mediante una llamada a SQLMoreResults. Después de llamar a SQLMoreResults para instrucciones UPDATE, INSERT o DELETE , una aplicación puede llamar a SQLRowCount.

Si se ha producido un conjunto de resultados actual con filas no capturadas, SQLMoreResults descarta ese conjunto de resultados y hace que el siguiente conjunto de resultados o el recuento estén disponibles. Si se han procesado todos los resultados, SQLMoreResults devuelve SQL_NO_DATA. Para algunos controladores, los parámetros de salida y los valores devueltos no están disponibles hasta que se hayan procesado todos los conjuntos de resultados y los recuentos de filas. Para estos controladores, los parámetros de salida y los valores devueltos están disponibles cuando SQLMoreResults devuelve SQL_NO_DATA.

Los enlaces establecidos para el conjunto de resultados anterior siguen siendo válidos. Si las estructuras de columna son diferentes para este conjunto de resultados, llamar a SQLFetch o SQLFetchScroll puede producir un error o truncamiento. Para evitar esto, la aplicación tiene que llamar a SQLBindCol para volver a enlazar explícitamente según corresponda (o hacerlo estableciendo campos descriptores). Como alternativa, la aplicación puede llamar a SQLFreeStmt con una opción de SQL_UNBIND para desenlace todos los búferes de columna.

Los valores de los atributos de instrucción, como el tipo de cursor, la simultaneidad del cursor, el tamaño del conjunto de claves o la longitud máxima, pueden cambiar a medida que la aplicación navega por el lote mediante llamadas a SQLMoreResults. Si esto sucede, SQLMoreResults devolverá SQL_SUCCESS_WITH_INFO y SQLSTATE 01S02 (el valor de opción ha cambiado).

Al llamar a SQLCloseCursor o SQLFreeStmt con una opción de SQL_CLOSE, descarta todos los conjuntos de resultados y recuentos de filas que estaban disponibles como resultado de la ejecución del lote. El identificador de instrucción vuelve al estado asignado o preparado. Llamar a SQLCancel para cancelar una función en ejecución asincrónica cuando se ha ejecutado un lote y el identificador de instrucción se encuentra en el estado ejecutado, colocado en cursor o asincrónico da como resultado todos los conjuntos de resultados y recuentos de filas generados por el lote que se descarta si la llamada de cancelación se realizó correctamente. A continuación, la instrucción vuelve al estado preparado o asignado.

Si un lote de instrucciones o un procedimiento mezcla otras instrucciones SQL con instrucciones SELECT, UPDATE, INSERT y DELETE , estas otras instrucciones no afectan a SQLMoreResults.

Para obtener más información, vea Varios resultados.

Si una instrucción de actualización, inserción o eliminación buscada en un lote de instrucciones no afecta a ninguna fila del origen de datos, SQLMoreResults devuelve SQL_SUCCESS. Esto es diferente del caso de una instrucción de actualización, inserción o eliminación buscada que se ejecuta a través de SQLExecDirect, SQLExecute o SQLParamData, que devuelve SQL_NO_DATA si no afecta a ninguna fila en el origen de datos. Si una aplicación llama a SQLRowCount para recuperar el recuento de filas después de una llamada a SQLMoreResults no ha afectado a ninguna fila, SQLRowCount devolverá SQL_NO_DATA.

Para obtener información adicional sobre la secuenciación válida de funciones de procesamiento de resultados, vea Apéndice B: Tablas de transición de estado odbc.

Para obtener más información sobre SQL_PARAM_DATA_AVAILABLE y los parámetros de salida transmitidos, consulte Recuperación de parámetros de salida mediante SQLGetData.

Disponibilidad de recuentos de filas

Cuando un lote contiene varias instrucciones de generación de recuento de filas consecutivas, es posible que estos recuentos de filas se revierta en un solo recuento de filas. Por ejemplo, si un lote tiene cinco instrucciones insert, determinados orígenes de datos pueden devolver cinco recuentos de filas individuales. Algunos otros orígenes de datos devuelven solo un recuento de filas que representa la suma de los cinco recuentos de filas individuales.

Cuando un lote contiene una combinación de instrucciones de generación de conjuntos de resultados y de recuento de filas, es posible que los recuentos de filas estén disponibles o no. El comportamiento del controlador con respecto a la disponibilidad de recuentos de filas se enumera en el tipo de información de SQL_BATCH_ROW_COUNT disponible a través de una llamada a SQLGetInfo. Por ejemplo, supongamos que el lote contiene un SELECT, seguido de dos INSERTs y otro SELECT. A continuación, se pueden realizar los siguientes casos:

  • Los recuentos de filas correspondientes a las dos instrucciones INSERT no están disponibles en absoluto. La primera llamada a SQLMoreResults le colocará en el conjunto de resultados de la segunda instrucción SELECT .

  • Los recuentos de filas correspondientes a las dos instrucciones INSERT están disponibles individualmente. (Una llamada a SQLGetInfo no devuelve el bit de SQL_BRC_ROLLED_UP para el tipo de información SQL_BATCH_ROW_COUNT). La primera llamada a SQLMoreResults le colocará en el recuento de filas del primer INSERT y la segunda llamada le colocará en el recuento de filas del segundo INSERT. La tercera llamada a SQLMoreResults le colocará en el conjunto de resultados de la segunda instrucción SELECT .

  • Los recuentos de filas correspondientes a los dos INSERT se acumulan en un solo recuento de filas que está disponible. (Una llamada a SQLGetInfo devuelve el bit de SQL_BRC_ROLLED_UP para el tipo de información SQL_BATCH_ROW_COUNT). La primera llamada a SQLMoreResults le colocará en el recuento de filas inscritos y la segunda llamada a SQLMoreResults le colocará en el conjunto de resultados del segundo SELECT.

Algunos controladores hacen que los recuentos de filas solo estén disponibles para lotes explícitos y no para procedimientos almacenados.

Para información acerca de Vea
Cancelación del procesamiento de instrucciones Función SQLCancel
Capturar un bloque de datos o desplazarse por un conjunto de resultados Función SQLFetchScroll
Capturar una sola fila o un bloque de datos en una dirección de solo avance Función SQLFetch
Capturar parte o toda una columna de datos Función SQLGetData

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC
Recuperar parámetros de salida mediante SQLGetData