Conjunto de registros: Obtener registros de forma masiva (ODBC)

Artículo
04/03/2023

Este tema es aplicable a las clases ODBC de MFC.

La clase CRecordset proporciona compatibilidad con la captura masiva de filas, lo que significa que se pueden recuperar varios registros a la vez durante una sola captura, en lugar de recuperar un registro cada vez desde el origen de datos. Puede implementar la captura masiva de filas solo en una clase derivada CRecordset. El proceso de transferencia de datos desde el origen de datos al objeto del conjunto de registros se denomina intercambio masivo de campos de registro (RFX masivo). Tenga en cuenta que si no usa la captura masiva de filas en una clase derivada de CRecordset, los datos se transfieren a través del intercambio de campos de registros (RFX). Para obtener más información, vea Intercambio de campos de registros (RFX).

En este tema se explica:

Cómo admite CRecordset la captura masiva de filas.
Algunas consideraciones especiales al usar la captura masiva de filas.
Cómo implementar el intercambio masivo de campos de registro.

Cómo CRecordset admite la captura masiva de filas.

Antes de abrir el objeto del conjunto de registros, puede definir un tamaño de conjunto de filas con la función miembro SetRowsetSize. El tamaño del conjunto de filas especifica cuántos registros se deben recuperar durante una sola captura. Cuando se implementa la captura masiva de filas, el tamaño predeterminado del conjunto de filas es 25. Si no se implementa la captura masiva de filas, el tamaño del conjunto de filas permanece fijo en 1.

Después de inicializar el tamaño del conjunto de filas, llame a la función miembro Abrir. Aquí debe especificar la opción CRecordset::useMultiRowFetch del parámetro dwOptions para implementar la captura masiva de filas. Además, puede establecer la opción CRecordset::userAllocMultiRowBuffers. El mecanismo de intercambio masivo de campos de registro usa matrices para almacenar las varias filas de datos recuperados durante una captura. El marco puede asignar automáticamente estos búferes de almacenamiento, aunque tiene la posibilidad de asignarlos manualmente. Si especifica la opción CRecordset::userAllocMultiRowBuffers, se ocupará personalmente de realizar la asignación.

En la tabla siguiente se enumeran las funciones miembro proporcionadas por CRecordset para admitir la captura masiva de filas.

Función de miembro	Descripción
CheckRowsetError	Función virtual que controla los errores que se producen durante la captura.
DoBulkFieldExchange	Implementa el intercambio masivo de campos de registro. Se le llama automáticamente para transferir varias filas de datos del origen de datos al objeto del conjunto de registros.
GetRowsetSize	Recupera la configuración actual para el tamaño del conjunto de filas.
GetRowsFetched	Indica cuántas filas se recuperaron realmente después de una captura determinada. En la mayoría de los casos, este es el tamaño del conjunto de filas, a menos que se capturara un conjunto de filas incompleto.
GetRowStatus	Devuelve un estado de captura de una fila determinada dentro de un conjunto de filas.
RefreshRowset	Actualiza los datos y el estado de una fila determinada dentro de un conjunto de filas.
SetRowsetCursorPosition	Mueve el cursor a una fila determinada dentro de un conjunto de filas.
SetRowsetSize	Función virtual que cambia la configuración del tamaño del conjunto de filas al valor especificado.

Consideraciones especiales

Aunque la captura masiva de filas es una ganancia de rendimiento, ciertas características funcionan de forma diferente. Antes de decidir implementar la captura masiva de filas, tenga en cuenta lo siguiente:

El marco llama automáticamente a la función miembro DoBulkFieldExchange para transferir datos del origen de datos al objeto del conjunto de registros. Sin embargo, los datos no se transfieren del conjunto de registros al origen de datos. Al llamar a las funciones miembro AddNew, Edit, Delete o Update, se produce un error en una aserción. Aunque CRecordset actualmente no proporciona un mecanismo para actualizar filas masivas de datos, puede escribir sus propias funciones mediante la función SQLSetPosde la API ODBC. Para obtener más información acerca de SQLSetPos, vea la Referencia del programador de OLE DB.
Las funciones miembro IsDeleted, IsFieldDirty, IsFieldNull, IsFieldNullable, SetFieldDirty, y SetFieldNull no se pueden usar en conjuntos de registros que implementan la captura masiva de filas. Sin embargo, puede llamar a GetRowStatus en lugar de IsDeleted y a GetODBCFieldInfo en lugar de IsFieldNullable.
Las operaciones Move cambian la posición del conjunto de registros por conjunto de filas. Por ejemplo, supongamos que abre un conjunto de registros que tiene 100 registros con un tamaño inicial de conjunto de filas de 10. Open captura las filas de 1 a 10, con el registro actual colocado en la fila 1. Una llamada a MoveNext captura el siguiente conjunto de filas, no la fila siguiente. Este conjunto de filas consta de las filas 11 a 20, con el registro actual situado en la fila 11. Tenga en cuenta que MoveNext y Move( 1 ) no son equivalentes cuando se implementa la captura masiva de filas. Move( 1 ) recupera el conjunto de filas que comienza a 1 fila del registro actual. En este ejemplo, al llamar a Move( 1 ) después de llamar a Open, se captura el conjunto de filas que consta de las filas de la 2 a la 11, con el registro actual situado en la fila 2. Para obtener más información, consulte la función miembro Move.
A diferencia del intercambio de campos de registros, los asistentes no admiten el intercambio masivo de campos de registro. Esto significa que debe declarar manualmente los miembros de datos de campo e invalidar DoBulkFieldExchange manualmente escribiendo llamadas a las funciones RFX masivas. Para obtener más información, vea Funciones de intercambio de campos de registros en la referencia de la biblioteca de clases.

Cómo implementar el intercambio masivo de campos de registro

El intercambio masivo de campos de registro transfiere un conjunto de filas de datos del origen de datos al objeto del conjunto de registro. Las funciones RFX masivas usan matrices para almacenar estos datos, así como matrices para almacenar la longitud de cada elemento de datos del conjunto de filas. En la definición de clase, debe definir los miembros de datos de campo como punteros para acceder a las matrices de datos. Además, debe definir un conjunto de punteros para acceder a las matrices de longitudes. Los miembros de datos de parámetros no deben declararse como punteros; declarar miembros de datos de parámetros cuando se usa el intercambio masivo de campos de registros es lo mismo que declararlos al usar el intercambio de campos de registros. El siguiente código muestra un ejemplo sencillo:

class MultiRowSet : public CRecordset
{
public:
   // Field/Param Data
      // field data members
      long* m_rgID;
      LPSTR m_rgName;

      // pointers for the lengths
      // of the field data
      long* m_rgIDLengths;
      long* m_rgNameLengths;

      // input parameter data member
      CString m_strNameParam;

   .
   .
   .
}

Puede asignar estos búferes de almacenamiento manualmente o hacer que el marco realice la asignación. Para asignar los búferes manualmente, debe especificar la opción CRecordset::userAllocMultiRowBuffers del parámetro dwOptions en la función miembro Open. Asegúrese de establecer los tamaños de las matrices al menos igual que el tamaño del conjunto de filas. Si desea que el marco realice la asignación, debe inicializar los punteros a NULL. Normalmente, esto se hace en el constructor del objeto del conjunto de registros:

MultiRowSet::MultiRowSet( CDatabase* pDB )
   : CRecordset( pDB )
{
   m_rgID = NULL;
   m_rgName = NULL;
   m_rgIDLengths = NULL;
   m_rgNameLengths = NULL;
   m_strNameParam = "";

   m_nFields = 2;
   m_nParams = 1;

   .
   .
   .
}

Por último, debe invalidar la función miembro DoBulkFieldExchange. Para los miembros de datos del campo, llame a las funciones RFX masivas; para cualquier miembro de datos de parámetros, llame a las funciones RFX. Si abrió el conjunto de registros pasando una instrucción SQL o un procedimiento almacenado a Open, el orden en el que realice las llamadas RFX en bloque debe corresponder al orden de las columnas en el conjunto de registros; del mismo modo, el orden de las llamadas RFX para los parámetros debe corresponder al orden de los parámetros en la instrucción SQL o el procedimiento almacenado.

void MultiRowSet::DoBulkFieldExchange( CFieldExchange* pFX )
{
   // call the Bulk RFX functions
   // for field data members
   pFX->SetFieldType( CFieldExchange::outputColumn );
   RFX_Long_Bulk( pFX, _T( "[colRecID]" ),
                  &m_rgID, &m_rgIDLengths );
   RFX_Text_Bulk( pFX, _T( "[colName]" ),
                  &m_rgName, &m_rgNameLengths, 30 );

   // call the RFX functions for
   // for parameter data members
   pFX->SetFieldType( CFieldExchange::inputParam );
   RFX_Text( pFX, "NameParam", m_strNameParam );
}

Nota:

Debe llamar a la función miembro Close antes de que la clase derivada CRecordset salga del ámbito. Esto garantiza que cualquier memoria asignada por el marco se libere. Es una buena práctica de programación llamar siempre explícitamente a Close, independientemente de si se ha implementado la captura masiva de filas.

Para obtener más información sobre el intercambio de campos de registros (RFX), consulte Intercambio de campos de registros: Funcionamiento de RFX. Para obtener más información sobre el uso de parámetros, vea CFieldExchange::SetFieldType y Conjunto de registros: Parametrizar un conjunto de registros (ODBC).

Consulte también

Conjunto de registros (ODBC)
CRecordset::m_nFields
CRecordset::m_nParams

Compartir a través de