Clase `CRecordset`

Artículo
06/16/2023

Representa un conjunto de registros seleccionados de un origen de datos.

Sintaxis

class CRecordset : public CObject

Miembros

Constructores públicos

Nombre	Descripción
`CRecordset::CRecordset`	Construye un objeto `CRecordset`. La clase derivada debe proporcionar un constructor que llame a este.

Métodos públicos

Nombre	Descripción
`CRecordset::AddNew`	Prepara la adición de un nuevo registro. Llame a `Update` para completar la adición.
`CRecordset::CanAppend`	Devuelve un valor distinto de cero si se pueden agregar nuevos registros al conjunto de registros a través de la función miembro `AddNew`.
`CRecordset::CanBookmark`	Devuelve un valor distinto de cero si el conjunto de registros admite marcadores.
`CRecordset::Cancel`	Cancela una operación asincrónica o un proceso de un segundo subproceso.
`CRecordset::CancelUpdate`	Cancela las actualizaciones pendientes debido a una operación `AddNew` o `Edit`.
`CRecordset::CanRestart`	Devuelve un valor distinto de cero si se puede llamar a `Requery` para volver a ejecutar la consulta del conjunto de registros.
`CRecordset::CanScroll`	Devuelve un valor distinto de cero si puede desplazarse por los registros.
`CRecordset::CanTransact`	Devuelve un valor distinto de cero si el origen de datos admite transacciones.
`CRecordset::CanUpdate`	Devuelve un valor distinto de cero si se puede actualizar el conjunto de registros (se pueden agregar, actualizar o eliminar registros).
`CRecordset::CheckRowsetError`	Se llama a este método para controlar los errores generados durante la captura de registros.
`CRecordset::Close`	Cierra el conjunto de registros y el objeto `HSTMT` ODBC asociado a él.
`CRecordset::Delete`	Elimina el registro actual del conjunto de registros. Debe desplazarse explícitamente a otro registro tras la eliminación.
`CRecordset::DoBulkFieldExchange`	Se llama a este método para intercambiar filas masivas de datos desde el origen de datos al conjunto de registros. Implementa el intercambio masivo de campos de registro (RFX masivo).
`CRecordset::DoFieldExchange`	Se llama a este método para intercambiar datos (en ambas direcciones) entre los miembros de datos de campo del conjunto de registros y el registro correspondiente en el origen de datos. Implementa el intercambio de campos de registro (RFX).
`CRecordset::Edit`	Prepara la implementación de cambios en el registro actual. Llame a `Update` para completar los cambios.
`CRecordset::FlushResultSet`	Devuelve un valor distinto de cero si hay otro conjunto de resultados que se va a recuperar, cuando se usa una consulta predefinida.
`CRecordset::GetBookmark`	Asigna el valor de marcador de un registro al objeto de parámetro.
`CRecordset::GetDefaultConnect`	Se llama a este método para obtener la cadena de conexión predeterminada.
`CRecordset::GetDefaultSQL`	Se llama a este método para obtener la cadena SQL predeterminada que se va a ejecutar.
`CRecordset::GetFieldValue`	Devuelve el valor de un campo de un conjunto de registros.
`CRecordset::GetODBCFieldCount`	Devuelve el número de campos del conjunto de registros.
`CRecordset::GetODBCFieldInfo`	Devuelve tipos específicos de información sobre los campos de un conjunto de registros.
`CRecordset::GetRecordCount`	Devuelve el número de registros del conjunto de registros.
`CRecordset::GetRowsetSize`	Devuelve el número de registros que desea recuperar durante una misma captura.
`CRecordset::GetRowsFetched`	Devuelve el número real de filas recuperadas durante una captura.
`CRecordset::GetRowStatus`	Devuelve el estado de la fila después de una captura.
`CRecordset::GetSQL`	Obtiene la cadena SQL que se usa para seleccionar registros del conjunto de registros.
`CRecordset::GetStatus`	Obtiene el estado del conjunto de registros, el índice del registro actual y si se ha obtenido un recuento final de los registros.
`CRecordset::GetTableName`	Obtiene el nombre de la tabla en la que se basa el conjunto de registros.
`CRecordset::IsBOF`	Devuelve un valor distinto de cero si el conjunto de registros se ha colocado antes del primer registro. No hay registro actual.
`CRecordset::IsDeleted`	Devuelve un valor distinto de cero si el conjunto de registros se coloca en un registro eliminado.
`CRecordset::IsEOF`	Devuelve un valor distinto de cero si el conjunto de registros se ha colocado después del último registro. No hay registro actual.
`CRecordset::IsFieldDirty`	Devuelve un valor distinto de cero si el campo especificado en el registro actual ha cambiado.
`CRecordset::IsFieldNull`	Devuelve un valor distinto de cero si el campo especificado en el registro actual es NULL (no tiene ningún valor).
`CRecordset::IsFieldNullable`	Devuelve un valor distinto de cero si el campo especificado en el registro actual se puede establecer en NULL (no tiene ningún valor).
`CRecordset::IsOpen`	Devuelve un valor distinto de cero si se ha llamado anteriormente a `Open`.
`CRecordset::Move`	Coloca el conjunto de registros en un número especificado de registros a partir del registro actual, en cualquier dirección.
`CRecordset::MoveFirst`	Coloca el registro actual en el primer registro del conjunto de registros. Pruebe `IsBOF` primero.
`CRecordset::MoveLast`	Coloca el registro actual en el último registro o en el último conjunto de filas. Pruebe `IsEOF` primero.
`CRecordset::MoveNext`	Coloca el registro actual en el siguiente registro o en el siguiente conjunto de filas. Pruebe `IsEOF` primero.
`CRecordset::MovePrev`	Coloca el registro actual en el registro anterior o en el conjunto de filas anterior. Pruebe `IsBOF` primero.
`CRecordset::OnSetOptions`	Se llama a este método para establecer opciones (usadas al seleccionar) de la instrucción ODBC especificada.
`CRecordset::OnSetUpdateOptions`	Se llama a este método para establecer opciones (usadas al actualizar) de la instrucción ODBC especificada.
`CRecordset::Open`	Abre el conjunto de registros recuperando la tabla o realizando la consulta que el conjunto de registros representa.
`CRecordset::RefreshRowset`	Actualiza los datos y el estado de las filas especificadas.
`CRecordset::Requery`	Ejecuta de nuevo la consulta del conjunto de registros para actualizar los registros seleccionados.
`CRecordset::SetAbsolutePosition`	Coloca el conjunto de registros en el registro correspondiente al número de registro especificado.
`CRecordset::SetBookmark`	Coloca el conjunto de registros en el registro especificado por el marcador.
`CRecordset::SetFieldDirty`	Marca el campo especificado en el registro actual como cambiado.
`CRecordset::SetFieldNull`	Establece el valor del campo especificado en el registro actual en NULL (sin valor).
`CRecordset::SetLockingMode`	Establece el modo de bloqueo en bloqueo "optimista" (valor predeterminado) o "pesimista". Determina cómo se bloquean los registros para las actualizaciones.
`CRecordset::SetParamNull`	Establece el parámetro especificado en NULL (sin valor).
`CRecordset::SetRowsetCursorPosition`	Coloca el cursor en la fila especificada dentro del conjunto de filas.
`CRecordset::SetRowsetSize`	Especifica el número de registros que desea recuperar durante una captura.
`CRecordset::Update`	Completa una operación `AddNew` o `Edit` guardando los datos nuevos o editados en el origen de datos.

Miembros de datos públicos

Nombre	Descripción
`CRecordset::m_hstmt`	Contiene el identificador de instrucción ODBC del conjunto de registros. Escriba `HSTMT`.
`CRecordset::m_nFields`	Contiene el número de miembros de datos de campo en el conjunto de registros. Escriba `UINT`.
`CRecordset::m_nParams`	Contiene el número de miembros de datos de parámetro en el conjunto de registros. Escriba `UINT`.
`CRecordset::m_pDatabase`	Contiene un puntero al objeto `CDatabase` a través del cual el conjunto de registros está conectado a un origen de datos.
`CRecordset::m_strFilter`	Contiene un objeto `CString` que especifica una cláusula `WHERE` de Lenguaje de consulta estructurado (SQL). Se usa como filtro para seleccionar solo los registros que cumplan determinados criterios.
`CRecordset::m_strSort`	Contiene un objeto `CString` que especifica una cláusula `ORDER BY` de SQL. Se usa para controlar cómo se ordenan los registros.

Comentarios

Los objetos CRecordset, que se conocen como "conjuntos de registros", se suelen usar en dos formatos: conjuntos de registros dinámicos e instantáneas. Un conjunto de registros dinámicos permanece sincronizado con las actualizaciones de datos realizadas por otros usuarios. Una instantánea es una vista estática de los datos. Cada forma representa un conjunto de registros fijo en el momento en que se abre el conjunto de registros. Cuando se desplaza a un registro de un conjunto de registros dinámicos, se reflejan los cambios realizados en el registro, ya sea por otros usuarios o por otros conjuntos de registros de la aplicación.

Nota:

Si trabaja con clases de objetos de acceso a datos (DAO) en vez de con clases de conectividad abierta de bases de datos (ODBC), use la clase CDaoRecordset en su lugar. Para obtener más información, vea Información general: programación de bases de datos.

Para trabajar con cualquier tipo de conjunto de registros, normalmente se deriva una clase de conjunto de registros específica de la aplicación de CRecordset. Los conjuntos de registros seleccionan registros de un origen de datos, tras lo cual se puede hacer lo siguiente:

Desplazarse por los registros.
Actualizar los registros y especificar un modo de bloqueo
Filtrar el conjunto de registros para restringir qué registros se seleccionan de los que hay disponibles en el origen de datos
Ordenar el conjunto de registros.
Parametrizar el conjunto de registros para personalizar su selección con información no conocida hasta el tiempo de ejecución

Para usar su clase, abra una base de datos y construya un objeto de conjunto de registros, pasando el constructor un puntero al objeto CDatabase. Luego, llame a la función miembro Open del conjunto de registros, donde puede especificar si el objeto es un conjunto de registros dinámicos o una instantánea. La llamada a Open selecciona datos del origen de datos. Una vez abierto el objeto de conjunto de registros, use sus funciones miembro y miembros de datos para desplazarse por los registros y operar en ellos. Las operaciones disponibles dependen de si el objeto es un conjunto de registros dinámicos o una instantánea, de si se puede actualizar o es de solo lectura (esto depende de la funcionalidad del origen de datos de conectividad abierta de bases de datos) y de si ha implementado la captura masiva de filas. Para actualizar los registros que puedan haber cambiado o que se hayan agregado desde la llamada a Open, llame a la función miembro del objeto Requery. Llame a la función miembro del objeto Close y destruya el objeto cuando termine con ella.

En una clase CRecordset derivada, el intercambio de campos de registro (RFX) o el intercambio masivo de campos de registro (RFX masivo) se usa para admitir la lectura y actualización de los campos de registro.

Para obtener más información sobre los conjuntos de registros y el intercambio de campos de registro, vea los artículos Información general: programación de bases de datos, Conjunto de registros (ODBC), Conjunto de registros: obtener registros de forma masiva bloque (ODBC) e Intercambio de campos de registro (RFX). Para centrarse en los conjuntos de registros dinámicos y en las instantáneas, vea los artículos Conjunto de registros dinámicos e Instantánea.

Jerarquía de herencia

CObject

CRecordset

Requisitos

Encabezadoafxdb.h:

`CRecordset::AddNew`

Prepara la adición de un nuevo registro a la tabla.

virtual void AddNew();

Comentarios

Debe llamar a la función miembro Requery para ver el registro recién agregado. Los campos del registro son NULL inicialmente. (en la terminología de bases de datos, NULL significa "sin valor"; no es lo mismo que NULL en C++). Para completar la operación, debe llamar a la función miembro Update. Update guarda los cambios en el origen de datos.

Nota:

Si ha implementado la captura masiva de filas, no puede llamar a AddNew. Si lo hace, dará lugar a una aserción con errores. Aunque la clase CRecordset no proporciona un mecanismo para actualizar filas masivas de datos, puede escribir sus propias funciones mediante la función SQLSetPosde la API ODBC. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

AddNew prepara un registro nuevo y vacío usando los miembros de datos de campo del conjunto de registros. Después de llamar a AddNew, establezca los valores que desee en los miembros de datos de campo del conjunto de registros (para ello, no hay que llamar a la función miembro Edit; use Edit solo con los registros existentes). Cuando se llama a Update, los valores modificados en los miembros de datos del campo se guardan en el origen de datos.

Precaución

Si se desplaza a un nuevo registro antes de llamar a Update, el nuevo registro se pierde y no se muestra ninguna advertencia.

Si el origen de datos admite transacciones, puede incluir la llamada a AddNew como parte de una transacción. Para obtener más información sobre las transacciones, vea la clase CDatabase. Llame a CDatabase::BeginTrans antes de llamar a AddNew.

Nota:

En los conjuntos de registros dinámicos, los nuevos registros se agregan al conjunto de registros como último registro. Los registros agregados no se agregan a instantáneas; deberá llamar a Requery para actualizar el conjunto de registros.

No se puede llamar a AddNew en relación con un conjunto de registros a cuya función miembro Open no se ha llamado. Si se llama a AddNew en relación con un conjunto de registros al que no se puede anexar, se produce una excepción CDBException. Para determinar si el conjunto de registros se puede actualizar, llame a CanAppend.

Para obtener más información, vea los siguientes artículos: Conjunto de registros: cómo actualizan registros los conjuntos de registros (ODBC), Conjunto de registros: agregar, actualizar y eliminar registros (ODBC) y Transacción (ODBC).

Ejemplo

Vea Transacción: realizar una transacción en un conjunto de registros (ODBC).

`CRecordset::CanAppend`

Determina si el conjunto de registros abierto anteriormente permite agregar nuevos registros.

BOOL CanAppend() const;

Valor devuelto

Distinto de cero si el conjunto de registros permite agregar nuevos registros; de lo contrario, 0. CanAppend devolverá 0 si abrió el conjunto de registros como de solo lectura.

`CRecordset::CanBookmark`

Determina si el conjunto de registros permite marcar registros mediante marcadores.

BOOL CanBookmark() const;

Valor devuelto

Distinto de cero si el conjunto de registros admite marcadores; de lo contrario, 0.

Comentarios

Esta función es independiente de la opción CRecordset::useBookmarks del parámetro dwOptions de la función miembro Open. CanBookmark indica si el controlador ODBC y el tipo de cursor especificados admiten marcadores. CRecordset::useBookmarks indica si va a haber marcadores disponibles, siempre que se admitan.

Nota:

Los marcadores no se admiten en conjuntos de registros de solo avance.

Para obtener más información sobre los marcadores y la navegación por el conjunto de registros, vea los artículos Conjunto de registros: marcadores y posiciones absolutas (ODBC) y Conjunto de registros: desplazamiento (ODBC).

`CRecordset::Cancel`

Solicita que el origen de datos cancele una operación asincrónica en curso o un proceso de un segundo subproceso.

void Cancel();

Comentarios

Las clases ODBC de MFC ya no usan procesamiento asincrónico; para realizar una operación asincrónica, debe llamar directamente a la función SQLSetConnectOptionde API odbc . Para obtener más información, vea la sección sobre cómo ejecutar funciones de forma asincrónica de la guía del programador del SDK de ODBC.

`CRecordset::CancelUpdate`

Cancela las actualizaciones pendientes, debido a una operación Edit o AddNew, antes de llamar a Update.

void CancelUpdate();

Comentarios

Nota:

Esta función miembro no es aplicable a los conjuntos de registros que usan la captura masiva de filas, ya que estos conjuntos de registros no pueden llamar a Edit, AddNew o Update. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

Si la comprobación automática de campos con modificaciones está habilitada, CancelUpdate restaurará las variables miembro a los valores que tenían antes de que se llamara a Edit o a AddNew; de lo contrario, los cambios de valor permanecerán. De forma predeterminada, la comprobación automática de campos se habilita cuando se abre el conjunto de registros. Para deshabilitarla, debe especificar un valor CRecordset::noDirtyFieldCheck en el parámetro dwOptions de la función miembro Open.

Para obtener más información sobre cómo actualizar datos, vea Conjunto de registros: agregar, actualizar y eliminar registros (ODBC).

`CRecordset::CanRestart`

Determina si el conjunto de registros permite reiniciar la consulta (para actualizar sus registros) mediante una llamada a la función miembro Requery.

BOOL CanRestart() const;

Valor devuelto

Un valor distinto de cero si se puede volver a realizar la consulta; de lo contrario, 0.

`CRecordset::CanScroll`

Determina si el conjunto de registros permite el desplazamiento.

BOOL CanScroll() const;

Valor devuelto

Un valor distinto de cero si el conjunto de registros permite el desplazamiento; de lo contrario, 0.

Comentarios

Para obtener más información sobre cómo desplazarse, vea Conjunto de registros: desplazamiento (ODBC).

`CRecordset::CanTransact`

Determina si el conjunto de registros permite las transacciones.

BOOL CanTransact() const;

Valor devuelto

Un valor distinto de cero si el conjunto de registros permite las transacciones; de lo contrario, 0.

Comentarios

Para obtener más información, vea Transacción (ODBC).

`CRecordset::CanUpdate`

Determina si se puede actualizar el conjunto de registros.

BOOL CanUpdate() const;

Valor devuelto

Un valor distinto de cero si el conjunto de registros se puede actualizar; de lo contrario, 0.

Comentarios

Un conjunto de registros puede ser de solo lectura si el origen de datos subyacente es de solo lectura o si especificó CRecordset::readOnly en el parámetro dwOptions al abrir el conjunto de registros.

`CRecordset::CheckRowsetError`

Se llama a este método para controlar los errores generados durante la captura de registros.

virtual void CheckRowsetError(RETCODE nRetCode);

Parámetros

nRetCode
Código de retorno de una función de API ODBC. Para conocer más detalles, vea la sección Comentarios.

Comentarios

Esta función miembro virtual controla los errores que se producen cuando se capturan registros, y resulta útil durante la captura masiva de filas. Puede que le convenga considerar la posibilidad de invalidar CheckRowsetError para implementar su propio control de errores.

En una operación de navegación de cursor, como Open, Requery o cualquier operación Move, se llama a CheckRowsetError automáticamente. Se pasa el valor devuelto de la función de API ODBC SQLExtendedFetch. En la siguiente tabla se muestran los posibles valores del parámetro nRetCode.

nRetCode	Descripción
`SQL_SUCCESS`	La función se completó correctamente. No hay más información disponible.
`SQL_SUCCESS_WITH_INFO`	La función se completó correctamente, posiblemente con un error no irrecuperable. Se puede obtener más información llamando a `SQLError`.
`SQL_NO_DATA_FOUND`	Se han capturado todas las filas del conjunto de resultados.
`SQL_ERROR`	Se ha producido un error en la función. Se puede obtener más información llamando a `SQLError`.
`SQL_INVALID_HANDLE`	Se ha producido un error en la función debido a un identificador de entorno, de conexión o de instrucción no válido. Esto indica un error de programación. No hay más información disponible de `SQLError`.
`SQL_STILL_EXECUTING`	Una función que se inició de forma asincrónica sigue ejecutándose. De forma predeterminada, MFC nunca pasará este valor a `CheckRowsetError`; MFC seguirá llamando a `SQLExtendedFetch` hasta que deje de devolver `SQL_STILL_EXECUTING`.

Consulte Windows SDK para obtener más información sobre SQLError. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

`CRecordset::Close`

Cierra el conjunto de registros.

virtual void Close();

Comentarios

El código HSTMT ODBC y toda la memoria asignada al conjunto de registros se desasignan. Normalmente, después de llamar a Close se elimina el objeto de conjunto de registros de C++, si se asignó con new.

Puede volver a llamar a Open después de llamar a Close. Esto le permitirá usar el objeto de conjunto de registros. La alternativa es llamar a Requery.

Ejemplo

// Construct a snapshot object
CCustomer rsCustSet(NULL);

if (!rsCustSet.Open())
return;

// Use the snapshot ...

// Close the snapshot
rsCustSet.Close();

// Destructor is called when the function exits

`CRecordset::CRecordset`

Construye un objeto CRecordset.

CRecordset(CDatabase* pDatabase = NULL);

Parámetros

pDatabase
Contiene un puntero a un objeto CDatabase o el valor NULL. Si no es NULL y no se ha llamado a la función miembro Open del objeto CDatabase para conectarlo al origen de datos, el conjunto de registros intenta abrirlo automáticamente durante la llamada a Open en sí. Si se pasa NULL, se crea un objeto CDatabase y se conecta automáticamente usando la información del origen de datos que se especificó al derivar la clase del conjunto de registros con ClassWizard.

Comentarios

Se puede usar CRecordset directamente o derivar una clase específica de la aplicación de CRecordset. Se puede usar ClassWizard para derivar las clases del conjunto de registros.

Nota:

Una clase derivada debe proporcionar su propio constructor. En el constructor de la clase derivada, llame al constructor CRecordset::CRecordset, pasándole los parámetros adecuados.

Pase NULL al constructor del conjunto de registros para construir un objeto CDatabase y conectarlo automáticamente. Se trata de un método rápido bastante útil que no requiere construir y conectar un objeto CDatabase antes de construir el conjunto de registros.

Ejemplo

Para obtener más información, vea Conjunto de registros: declarar una clase para una tabla (ODBC).

`CRecordset::Delete`

Elimina el registro actual.

virtual void Delete();

Comentarios

Después de una eliminación correcta, los miembros de datos de campo del conjunto de registros se establecen en un valor NULL y se debe llamar explícitamente a una de las funciones Move para retirar el registro eliminado. Una vez retirado el registro eliminado, no es posible volver a él. Si el origen de datos admite transacciones, puede incluir la llamada a Delete como parte de una transacción. Para obtener más información, vea Transacción (ODBC).

Nota:

Si ha implementado la captura masiva de filas, no puede llamar a Delete. Si lo hace, dará lugar a una aserción con errores. Aunque la clase CRecordset no proporciona un mecanismo para actualizar filas masivas de datos, puede escribir sus propias funciones mediante la función SQLSetPosde la API ODBC. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

Precaución

El conjunto de registros debe poder actualizarse y debe haber un registro válido actualmente en el conjunto de registros cuando se llame a Delete; de lo contrario, se produce un error. Por ejemplo, si elimina un registro pero no se desplaza a uno nuevo antes de volver a llamar a Delete, Delete inicia una excepción CDBException.

A diferencia de AddNew y Edit, una llamada a Delete no va seguida de una llamada a Update. Si se produce un error en una llamada a Delete, los miembros de datos de campo permanecen inalterados.

Ejemplo

En este ejemplo se muestra un conjunto de registros creado en el marco de una función. En el ejemplo se da por sentada la existencia de m_dbCust, una variable miembro de tipo CDatabase que ya está conectada al origen de datos.

// Create a derived CRecordset object
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if (rsCustSet.IsEOF() || !rsCustSet.CanUpdate() ||
   !rsCustSet.CanTransact())
{
   return;
}

m_dbCust.BeginTrans();

// Perhaps scroll to a new record...
// Delete the current record
rsCustSet.Delete();

// Finished commands for this transaction
if (IDYES == AfxMessageBox(_T("Commit transaction?"), MB_YESNO))
m_dbCust.CommitTrans();
else // User changed mind
m_dbCust.Rollback();

`CRecordset::DoBulkFieldExchange`

Se llama a este método para intercambiar filas masivas de datos desde el origen de datos al conjunto de registros. Implementa el intercambio masivo de campos de registro (RFX masivo).

virtual void DoBulkFieldExchange(CFieldExchange* pFX);

Parámetros

pFX
Puntero a un objeto CFieldExchange . El marco ya habrá configurado este objeto para especificar un contexto para la operación de intercambio de campos.

Comentarios

Cuando se implementa la captura masiva de filas, el marco llama a esta función miembro para transferir automáticamente datos desde el origen de datos al objeto de conjunto de registros. DoBulkFieldExchange también enlaza los miembros de datos de parámetros (si los hay) a marcadores de posición de parámetro en la cadena de instrucción SQL para la selección del conjunto de registros.

Si no se implementa la captura masiva de filas, el marco llama a DoFieldExchange. Para implementar la captura masiva de filas, se debe especificar la opción CRecordset::useMultiRowFetch en el parámetro dwOptions de la función miembro Open.

Nota:

DoBulkFieldExchange solo está disponible si se usa una clase derivada de CRecordset. Si ha creado un objeto de conjunto de registros directamente desde CRecordset, debe llamar a la función miembro GetFieldValue para recuperar datos.

El intercambio masivo de campos de registro (RFX masivo) es similar al intercambio de campos de registro (RFX). Los datos se transfieren automáticamente desde el origen de datos al objeto de conjunto de registros. Sin embargo, no se puede llamar a AddNew, Edit, Delete ni Update para transferir los cambios de vuelta al origen de datos. Actualmente, la clase CRecordset no proporciona un mecanismo para actualizar filas de datos masivas, pero puede escribir sus propias funciones mediante la función de la API ODBC SQLSetPos.

ClassWizard no admite el intercambio masivo de campos de registro; por lo tanto, debe invalidar DoBulkFieldExchange manualmente escribiendo llamadas a las funciones de RFX masivo. Para obtener más información sobre estas funciones, vea Funciones de intercambio de campos de registros.

Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC). Para obtener información relacionada, vea Intercambio de campos de registros (RFX).

`CRecordset::DoFieldExchange`

Se llama a este método para intercambiar datos (en ambas direcciones) entre los miembros de datos de campo del conjunto de registros y el registro correspondiente en el origen de datos. Implementa el intercambio de campos de registro (RFX).

virtual void DoFieldExchange(CFieldExchange* pFX);

Parámetros

pFX
Puntero a un objeto CFieldExchange . El marco ya habrá configurado este objeto para especificar un contexto para la operación de intercambio de campos.

Comentarios

Cuando no se implementa la captura masiva de filas, el marco llama a esta función miembro para intercambiar automáticamente datos entre los miembros de datos de campo del objeto de conjunto de registros y las columnas correspondientes del registro actual en el origen de datos. DoFieldExchange también enlaza los miembros de datos de parámetros (si los hay) a marcadores de posición de parámetro en la cadena de instrucción SQL para la selección del conjunto de registros.

Si se implementa la captura masiva de filas, el marco llama a DoBulkFieldExchange. Para implementar la captura masiva de filas, se debe especificar la opción CRecordset::useMultiRowFetch en el parámetro dwOptions de la función miembro Open.

Nota:

DoFieldExchange solo está disponible si se usa una clase derivada de CRecordset. Si ha creado un objeto de conjunto de registros directamente desde CRecordset, debe llamar a la función miembro GetFieldValue para recuperar datos.

El intercambio de datos de campo, denominado intercambio de campos de registro (RFX), funciona en ambas direcciones: de los miembros de datos de campo del objeto de conjunto de registros a los campos del registro del origen de datos, y del registro del origen de datos al objeto de conjunto de registros.

Normalmente, la única acción que debe realizar para implementar DoFieldExchange para la clase de conjunto de registros derivada es crear la clase con ClassWizard y especificar los nombres y los tipos de datos de los miembros de datos de campo. También puede agregar código a lo que ClassWizard escriba para especificar miembros de datos de parámetros o para tratar las columnas enlazadas dinámicamente. Para más información, consulte Conjunto de registros: enlazar dinámicamente columnas de datos (ODBC).

Al declarar la clase de conjunto de registros derivada con ClassWizard, el asistente escribe una invalidación de DoFieldExchange automáticamente, que se parece al ejemplo siguiente:

void CCustomer::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputColumn);
   // Macros such as RFX_Text() and RFX_Int() are dependent on the
   // type of the member variable, not the type of the field in the database.
   // ODBC will try to automatically convert the column value to the requested type
   RFX_Long(pFX, _T("[CustomerID]"), m_CustomerID);
   RFX_Text(pFX, _T("[ContactFirstName]"), m_ContactFirstName);
   RFX_Text(pFX, _T("[PostalCode]"), m_PostalCode);
   RFX_Text(pFX, _T("[L_Name]"), m_L_Name);
   RFX_Long(pFX, _T("[BillingID]"), m_BillingID);

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param"), m_strParam);
}

Para obtener más información sobre las funciones RFX, vea Funciones de intercambio de campos de registros.

Para obtener más ejemplos y detalles sobre DoFieldExchange, vea Intercambio de campos de registros: funcionamiento de RFX. Para obtener información general sobre RFX, vea Intercambio de campos de registros.

`CRecordset::Edit`

Permite realizar cambios en el registro actual.

virtual void Edit();

Comentarios

Después de llamar a Edit, puede cambiar los miembros de datos de campo restableciendo directamente sus valores. La operación se completa cuando se llama a la función miembro Update para guardar los cambios en el origen de datos.

Nota:

Si ha implementado la captura masiva de filas, no puede llamar a Edit. Si lo hace, dará lugar a una aserción con errores. Aunque la clase CRecordset no proporciona un mecanismo para actualizar filas masivas de datos, puede escribir sus propias funciones mediante la función SQLSetPosde la API ODBC. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

Edit guarda los valores de los miembros de datos del conjunto de registros. Si llama a Edit, realice cambios y vuelva a llamar a Edit. Los valores del registro se restauran a como estaban antes de la primera llamada a Edit.

En algunos casos, posiblemente sea conveniente actualizar una columna haciendo que sea NULL (esto es, no contiene datos). Para ello, llame a SetFieldNull con un parámetro TRUE para marcar el campo como NULL; esto también hace que la columna se actualice. Si quiere que un campo se escriba en el origen de datos aunque su valor no haya cambiado, llame a SetFieldDirty con un parámetro TRUE. Esto funciona incluso cuando el campo tenía el valor NULL.

Si el origen de datos admite transacciones, puede incluir la llamada a Edit como parte de una transacción. Llame a CDatabase::BeginTrans antes de llamar a Edit y después de abrir el conjunto de registros. Además, llamar a CDatabase::CommitTrans no es un sustituto de llamar a Update para completar la operación Edit. Para obtener más información sobre las transacciones, vea la clase CDatabase.

Dependiendo del modo de bloqueo actual, el registro que se está actualizando puede estar bloqueado por Edit hasta que se llame a Update o se desplace a otro registro, o bien puede bloquearse solo durante la llamada a Edit. El modo de bloqueo se puede cambiar con SetLockingMode.

El valor anterior del registro actual se restaura si se desplaza a un nuevo registro antes de llamar a Update. Se produce una excepción CDBException si se llama a Edit en un conjunto de registros que no se puede actualizar o si no hay ningún registro actual.

Para obtener más información, vea los artículos Transacción (ODBC) y Conjunto de registros: bloquear registros (ODBC).

Ejemplo

// To edit a record, first set up the edit buffer
rsCustSet.Edit();

// Then edit field data members for the record
rsCustSet.m_BillingID = 2795;
rsCustSet.m_ContactFirstName = _T("Jones Mfg");

// Finally, complete the operation
if (!rsCustSet.Update())
{
   // Handle the failure to update
   AfxMessageBox(_T("Couldn't update record!"));
}

`CRecordset::FlushResultSet`

Recupera el siguiente conjunto de resultados de una consulta predefinida (procedimiento almacenado) si hay varios conjuntos de resultados.

BOOL FlushResultSet();

Valor devuelto

Un valor distinto de cero si hay más conjuntos de resultados que se van a recuperar; de lo contrario, 0.

Comentarios

Solo debe llamar a FlushResultSet cuando haya terminado con el cursor en el conjunto de resultados actual. Cuando se recupera el siguiente conjunto de resultados llamando a FlushResultSet, el cursor no es válido en ese conjunto de resultados; debe llamar a la función miembro MoveNext después de llamar a FlushResultSet.

Si una consulta predefinida usa un parámetro de salida o parámetros de entrada/salida, debe llamar a FlushResultSet hasta que devuelva FALSE(un valor 0) para obtener estos valores de parámetro.

FlushResultSet llama a la función de API ODBC SQLMoreResults. Si SQLMoreResults devuelve SQL_ERROR o SQL_INVALID_HANDLE, FlushResultSet producirá una excepción. Consulte Windows SDK para obtener más información sobre SQLMoreResults.

Si quiere llamar a FlushResultSet, el procedimiento almacenado debe tener campos enlazados.

Ejemplo

En el código siguiente se da por hecho que COutParamRecordset es un objeto derivado de CRecordset basado en una consulta predefinida con un parámetro de entrada y un parámetro de salida, y que tiene varios conjuntos de resultados. Observe la estructura de la invalidación de DoFieldExchange.

// DoFieldExchange override
//
// Only necessary to handle parameter bindings.
// Don't use CRecordset-derived class with bound
// fields unless all result sets have same schema
// OR there is conditional binding code.
void CCourses::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputParam);
   RFX_Long(pFX, _T("Param1"), m_nCountParam);
   // The "Param1" name here is a dummy name 
   // that is never used

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param2"), m_strNameParam);
   // The "Param2" name here is a dummy name 
   // that is never used
}

// Assume db is an already open CDatabase object
CCourses rs(&m_dbCust);
rs.m_strNameParam = _T("History");

// Get the first result set
// NOTE: SQL Server requires forwardOnly cursor 
//       type for multiple rowset returning stored 
//       procedures
rs.Open(CRecordset::forwardOnly,
   _T("{? = CALL GetCourses( ? )}"),
   CRecordset::readOnly);

// Loop through all the data in the first result set
while (!rs.IsEOF())
{
   CString strFieldValue;
   for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
   {
      rs.GetFieldValue(nIndex, strFieldValue);

      // TO DO: Use field value string.
   }
   rs.MoveNext();
}

// Retrieve other result sets...
while (rs.FlushResultSet())
{
   // must call MoveNext because cursor is invalid
   rs.MoveNext();

   while (!rs.IsEOF())
   {
      CString strFieldValue;
      for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
      {
         rs.GetFieldValue(nIndex, strFieldValue);

         // TO DO: Use field value string.
      }
      rs.MoveNext();
   }
}


// All result sets have been flushed. Cannot
// use the cursor, but the output parameter,
// m_nCountParam, has now been written.
// Note that m_nCountParam is not valid until
// CRecordset::FlushResultSet has returned FALSE,
// indicating no more result sets will be returned.

// TO DO: Use m_nCountParam

// Cleanup
rs.Close();

`CRecordset::GetBookmark`

Obtiene el valor de marcador del registro actual.

void GetBookmark(CDBVariant& varBookmark);

Parámetros

varBookmark
Referencia a un objeto CDBVariant que representa el marcador en el registro actual.

Comentarios

Llame a CanBookmark para determinar si se admiten marcadores en el conjunto de registros. Para que los marcadores estén disponibles (si se admiten), debe establecer la opción CRecordset::useBookmarks en el parámetro dwOptions de la función miembro Open.

Nota:

Si no se admiten marcadores o no están disponibles, la llamada a GetBookmark producirá una excepción. Los marcadores no se admiten en conjuntos de registros de solo avance.

GetBookmark asigna el valor del marcador del registro actual a un objeto CDBVariant. Para volver a ese registro en cualquier momento después de pasar a otro registro, llame a SetBookmark con el objeto CDBVariant correspondiente.

Nota:

Después de determinadas operaciones del conjunto de registros, es posible que los marcadores dejen de ser válidos. Por ejemplo, si llama a GetBookmark seguido de Requery, es posible que no pueda volver al registro con SetBookmark. Llame a CDatabase::GetBookmarkPersistence para comprobar si puede llamar a SetBookmark de forma segura.

`CRecordset::GetDefaultConnect`

Se llama a este método para obtener la cadena de conexión predeterminada.

virtual CString GetDefaultConnect();

Valor devuelto

Un valor de tipo CString que contiene la cadena de conexión predeterminada.

Comentarios

El marco llama a esta función miembro para obtener la cadena de conexión predeterminada del origen de datos en el que se basa el conjunto de registros. ClassWizard implementa esta función identificando el mismo origen de datos que se usa en ClassWizard para obtener información sobre las tablas y las columnas. Usar esta conexión predeterminada mientras desarrolla la aplicación probablemente le resulte conveniente, pero seguramente esta conexión predeterminada no sea adecuada para los usuarios de la aplicación. Si es así, debe volver a implementar esta función, descartando la versión de ClassWizard. Para obtener más información sobre las cadenas de conexión Origen de datos (ODBC).

`CRecordset::GetDefaultSQL`

Se llama a este método para obtener la cadena SQL predeterminada que se va a ejecutar.

virtual CString GetDefaultSQL();

Valor devuelto

Un valor de tipo CString que contiene la instrucción SQL predeterminada.

Comentarios

El marco llama a esta función miembro para obtener la instrucción SQL predeterminada en la que se basa el conjunto de registros. Puede ser un nombre de tabla o una instrucción SQL SELECT.

La instrucción SQL predeterminada se define indirectamente al declarar la clase de conjunto de registros con ClassWizard, tarea que ClassWizard realiza automáticamente.

Si necesita la cadena de instrucción SQL para uso propio, llame a GetSQL, que devuelve la instrucción SQL utilizada para seleccionar los registros del conjunto de registros cuando se abrió. La cadena SQL predeterminada se puede editar en la invalidación de GetDefaultSQL de la clase. Por ejemplo, se podría especificar una llamada a una consulta predefinida mediante una instrucción CALL (no obstante, cabe reseñar que si GetDefaultSQL se edita, también habrá que modificar m_nFields para que coincida con el número de columnas del origen de datos).

Para obtener más información, vea Conjunto de registros: declarar una clase para una tabla (ODBC).

Precaución

El nombre de la tabla estará vacío si el marco no pudo identificar un nombre de tabla, si se proporcionaron varios nombres de tabla o si una instrucción CALL no se pudo interpretar. Cuando use una instrucción CALL, no inserte espacios en blanco entre la llave y la palabra clave CALL, ni tampoco antes de la llave o de la palabra clave SELECT en una instrucción SELECT.

`CRecordset::GetFieldValue`

Recupera datos de campo en el registro actual.

void GetFieldValue(
    LPCTSTR lpszName,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringA& strValue
);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringW& strValue
);

void GetFieldValue(
    short nIndex,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    short nIndex,
    CStringA& strValue);

void GetFieldValue(
    short nIndex,
    CStringW& strValue);

Parámetros

lpszName
El nombre de un campo.

varValue Referencia a un objeto CDBVariant que almacenará el valor del campo.

nFieldType
Tipo de datos de C ODBC del campo. Mediante el valor predeterminado, DEFAULT_FIELD_TYPE, se fuerza a GetFieldValue a determinar el tipo de datos de C del tipo de datos SQL, según la siguiente tabla. De lo contrario, el tipo de datos se puede especificar directamente o elegir un tipo de datos compatible; por ejemplo, en SQL_C_CHAR se puede almacenar cualquier tipo de datos.

tipo de datos C	tipo de datos de SQL
`SQL_C_BIT`	`SQL_BIT`
`SQL_C_UTINYINT`	`SQL_TINYINT`
`SQL_C_SSHORT`	`SQL_SMALLINT`
`SQL_C_SLONG`	`SQL_INTEGER`
`SQL_C_FLOAT`	`SQL_REAL`
`SQL_C_DOUBLE`	`SQL_FLOATSQL_DOUBLE`
`SQL_C_TIMESTAMP`	`SQL_DATESQL_TIMESQL_TIMESTAMP`
`SQL_C_CHAR`	`SQL_NUMERICSQL_DECIMALSQL_BIGINTSQL_CHARSQL_VARCHARSQL_LONGVARCHAR`
`SQL_C_BINARY`	`SQL_BINARYSQL_VARBINARYSQL_LONGVARBINARY`

Para obtener más información sobre los tipos de datos ODBC, vea los temas sobre los tipos de datos SQL y los tipos de datos de C en el Apéndice D de Windows SDK.

nIndex
Índice de base cero de un campo.

strValue
Referencia a un objeto CString que almacenará el valor del campo convertido en texto, independientemente del tipo de datos del campo.

Comentarios

Un campo se puede buscar por nombre o por índice. El valor de campo se puede almacenar en un objeto CDBVariant o en un objeto CString.

Si se ha implementado la captura masiva de filas, el registro actual siempre se coloca como primer registro de un conjunto de filas. Para usar GetFieldValue en un registro dentro de un conjunto de filas determinado, primero debe llamar a la función miembro SetRowsetCursorPosition para mover el cursor a la fila deseada dentro de ese conjunto de filas. A continuación, llame a GetFieldValue para esa fila. Para implementar la captura masiva de filas, se debe especificar la opción CRecordset::useMultiRowFetch en el parámetro dwOptions de la función miembro Open.

Puede usar GetFieldValue para capturar dinámicamente campos en tiempo de ejecución en lugar de enlazarlos estáticamente en tiempo de diseño. Por ejemplo, si ha declarado un objeto de conjunto de registros directamente desde CRecordset, debe usar GetFieldValue para recuperar los datos del campo. El intercambio de campos de registros (RFX) o el intercambio masivo de campos de registro (RFX masivo) no se implementa.

Nota:

Si declara un objeto de conjunto de registros sin derivarlo de CRecordset, no tenga cargada la biblioteca de cursores ODBC. Esta biblioteca de cursores requiere que el conjunto de registros tenga al menos una columna enlazada, pero cuando CRecordset se usa directamente, ninguna de las columnas está enlazada. Las funciones miembro CDatabase::OpenEx y CDatabase::Open controlan si se va a cargar la biblioteca de cursores.

GetFieldValue llama a la función de API ODBC SQLGetData. Si el controlador genera el valor SQL_NO_TOTAL como longitud real del valor del campo, GetFieldValue produce una excepción. Consulte Windows SDK para obtener más información sobre SQLGetData.

Ejemplo

En el siguiente código de ejemplo se muestran las llamadas a GetFieldValue de un objeto de conjunto de registros declarado directamente desde CRecordset.

// Create and open a database object;
// do not load the cursor library
CDatabase db;
db.OpenEx(NULL, CDatabase::forceOdbcDialog);

// Create and open a recordset object
// directly from CRecordset. Note that a
// table must exist in a connected database.
// Use forwardOnly type recordset for best
// performance, since only MoveNext is required
CRecordset rs(&db);
rs.Open(CRecordset::forwardOnly, _T("SELECT * FROM Customer"));

// Create a CDBVariant object to
// store field data
CDBVariant varValue;

// Loop through the recordset,
// using GetFieldValue and
// GetODBCFieldCount to retrieve
// data in all columns
short nFields = rs.GetODBCFieldCount();
while (!rs.IsEOF())
{
   for (short index = 0; index < nFields; index++)
   {
      rs.GetFieldValue(index, varValue);
      // do something with varValue
   }
   rs.MoveNext();
}

rs.Close();
db.Close();

Nota:

A diferencia de la clase de DAO CDaoRecordset, CRecordset no tiene una función miembro SetFieldValue. Si crea un objeto directamente desde CRecordset, será de solo lectura de facto.

Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

`CRecordset::GetODBCFieldCount`

Recupera el número total de campos del objeto de conjunto de registros.

short GetODBCFieldCount() const;

Valor devuelto

El número de campos del conjunto de registros.

Comentarios

Para obtener más información sobre cómo crear conjuntos de registros, vea Conjunto de registros: crear y cerrar conjuntos de registros (ODBC).

`CRecordset::GetODBCFieldInfo`

Obtiene información sobre los campos del conjunto de registros.

void GetODBCFieldInfo(
    LPCTSTR lpszName,
    CODBCFieldInfo& fieldinfo);

void GetODBCFieldInfo(
    short nIndex,
    CODBCFieldInfo& fieldinfo);

Parámetros

lpszName
El nombre de un campo.

fieldinfo
Referencia a una estructura CODBCFieldInfo.

nIndex
Índice de base cero de un campo.

Comentarios

Una versión de la función permite buscar un campo por nombre. La otra versión permite buscar un campo por índice.

Para obtener una descripción sobre la información devuelta, vea la estructura CODBCFieldInfo.

Para obtener más información sobre cómo crear conjuntos de registros, vea Conjunto de registros: crear y cerrar conjuntos de registros (ODBC).

`CRecordset::GetRecordCount`

Determina el tamaño del conjunto de registros.

long GetRecordCount() const;

Valor devuelto

Número de registros en el conjunto de registros; 0 si el conjunto de registros no contiene ningún registro, o -1 si el número de registros no se puede determinar.

Comentarios

Precaución

El recuento de registros se mantiene como una "marca de agua alta"; el registro numerado más alto se sigue viendo a medida que el usuario va desplazándose por los registros. El número total de registros solo se conoce después de que el usuario haya ido más allá del último registro. Por motivos de rendimiento, el recuento no se actualiza cuando se llama a MoveLast. Para contar los registros por sí mismo, llame a MoveNext repetidamente hasta que IsEOF devuelva un valor distinto de cero. Agregar un registro a través de CRecordset:AddNew y Update aumenta el recuento, mientras que eliminar un registro a través de CRecordset::Delete lo reduce.

`CRecordset::GetRowsetSize`

Obtiene la configuración actual del número de filas que desea recuperar durante una captura determinada.

DWORD GetRowsetSize() const;

Valor devuelto

Número de filas que se van a recuperar durante una captura determinada.

Comentarios

Si usa la captura masiva de filas, el tamaño predeterminado del conjunto de filas cuando se abre el conjunto de registros es 25; de lo contrario, es 1.

Para implementar la captura masiva de filas, se debe especificar la opción CRecordset::useMultiRowFetch en el parámetro dwOptions de la función miembro Open. Para cambiar el valor del tamaño del conjunto de filas, llame a SetRowsetSize.

Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

`CRecordset::GetRowsFetched`

Determina cuántos registros se han recuperado después de una captura.

DWORD GetRowsFetched() const;

Valor devuelto

Número de filas recuperadas del origen de datos tras una captura determinada.

Comentarios

Esto es útil cuando se ha implementado la captura masiva de filas. El tamaño del conjunto de filas suele indicar cuántas filas se van a recuperar en una captura. Sin embargo, el número total de filas del conjunto de registros también afecta al número de filas que se van a recuperar en un conjunto de filas. Por ejemplo, si el conjunto de registros tiene 10 registros con un valor de tamaño de conjunto de filas de 4, el recorrido en bucle por el conjunto de registros llamando a MoveNext tendrá como consecuencia que el conjunto de filas final va a tener solo dos registros.

Para implementar la captura masiva de filas, se debe especificar la opción CRecordset::useMultiRowFetch en el parámetro dwOptions de la función miembro Open. Para especificar el tamaño del conjunto de filas, llame a SetRowsetSize.

Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

Ejemplo

CMultiCustomer rs(&m_dbCust);

// Set the rowset size
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// loop through the recordset by rowsets
while (!rs.IsEOF())
{
   for (int rowCount = 0; rowCount < (int)rs.GetRowsFetched(); rowCount++)
   {
      // do something
   }

   rs.MoveNext();
}

rs.Close();

`CRecordset::GetRowStatus`

Obtiene el estado de una fila del conjunto de filas actual.

WORD GetRowStatus(WORD wRow) const;

Parámetros

wRow
Posición, según un índice de base 1, de una fila del conjunto de filas actual. Este valor puede oscilar entre 1 y el tamaño del conjunto de filas.

Valor devuelto

Valor de estado de la fila. Para conocer más detalles, vea la sección Comentarios.

Comentarios

GetRowStatus devuelve un valor que indica bien un cambio de estado en la fila desde que se recuperó por última vez del origen de datos, bien que no se capturó ninguna fila correspondiente a wRow. La tabla siguiente muestra los valores devueltos posibles.

Valor de estado	Descripción
`SQL_ROW_SUCCESS`	La fila no ha cambiado.
`SQL_ROW_UPDATED`	La fila se ha actualizado.
`SQL_ROW_DELETED`	Se ha eliminado la fila.
`SQL_ROW_ADDED`	La fila se ha añadido.
`SQL_ROW_ERROR`	La fila no se puede recuperar debido a un error.
`SQL_ROW_NOROW`	No hay ninguna fila que corresponda a `wRow`.

Para obtener más información, vea la función de API ODBC SQLExtendedFetch en Windows SDK.

`CRecordset::GetStatus`

Determina el índice del registro actual en el conjunto de registros y si se ha visto el último registro.

void GetStatus(CRecordsetStatus& rStatus) const;

Parámetros

rStatus
Referencia a un objeto CRecordsetStatus. Para obtener más información, vea Comentarios.

Comentarios

CRecordset intenta realizar un seguimiento del índice, pero en algunas circunstancias puede que esto no sea posible. Vea GetRecordCount para obtener una explicación.

La estructura CRecordsetStatus tiene la siguiente forma:

struct CRecordsetStatus
{
    long m_lCurrentRecord;
    BOOL m_bRecordCountFinal;
};

Los dos miembros de CRecordsetStatus tienen los siguientes significados:

m_lCurrentRecord Contiene el índice de base cero del registro actual en el conjunto de registros, si se conoce. Si no se puede determinar el índice, este miembro contiene AFX_CURRENT_RECORD_UNDEFINED (-2). Si IsBOF es TRUE (el conjunto de registros está vacío o ha habido un intento de desplazarse antes del primer registro), m_lCurrentRecord se establece en AFX_CURRENT_RECORD_BOF (-1). Si se está en el primer registro, se establece en 0, si se está en el segundo, en 1, y así sucesivamente.
m_bRecordCountFinal Valor distinto de cero si se ha determinado el número total de registros del conjunto de registros. Por lo general, esto debe realizarse empezando por el principio del conjunto de registros y llamando a MoveNext hasta que IsEOF devuelve un valor distinto de cero. Si el valor de este miembro es cero, el recuento de registros devuelto por GetRecordCount, si no es -1, es solo un recuento de "marca de agua alta" de los registros.

`CRecordset::GetSQL`

Llame a esta función miembro para obtener la instrucción SQL que se usó para seleccionar los registros del conjunto de registros cuando se abrió.

const CString& GetSQL() const;

Valor devuelto

Referencia de const a un objeto CString que contiene la instrucción SQL.

Comentarios

Por lo general, se trata de una instrucción SQL SELECT. La cadena devuelta por GetSQL es de solo lectura.

La cadena devuelta por GetSQL suele ser diferente de cualquier cadena que pueda haber pasado al conjunto de registros en el parámetro lpszSQL a la función miembro Open. Esto se debe a que el conjunto de registros crea una instrucción SQL completa en función de lo que se ha pasado a Open, de lo que se ha especificado con ClassWizard, de lo que se haya podido especificar en los miembros de datos m_strFilter y m_strSort y de cualquier parámetro que se haya especificado. Para obtener información detallada sobre cómo el conjunto de registros construye esta instrucción SQL, vea Conjunto de registros: cómo actualizan registros los conjuntos de registros (ODBC).

Nota:

Llame a esta función miembro solo después de llamar a Open.

`CRecordset::GetTableName`

Obtiene el nombre de la tabla SQL en la que se basa la consulta del conjunto de registros.

const CString& GetTableName() const;

Valor devuelto

Referencia de const a un objeto CString que contiene el nombre de la tabla, si el conjunto de registros se basa en una tabla; de lo contrario, una cadena vacía.

Comentarios

GetTableName solo es válido si el conjunto de registros se basa en una tabla, y no en una combinación de varias tablas o en una consulta predefinida (procedimiento almacenado). El nombre es de solo lectura.

Nota:

Llame a esta función miembro solo después de llamar a Open.

`CRecordset::IsBOF`

Devuelve un valor distinto de cero si el conjunto de registros se ha colocado antes del primer registro. No hay registro actual.

BOOL IsBOF() const;

Valor devuelto

Un valor distinto de cero si el conjunto de registros no contiene registros o si el usuario se ha desplazado de vuelta antes del primer registro; de lo contrario, 0.

Comentarios

Llame a esta función miembro antes de desplazarse de un registro a otro para saber si ha ido antes del primer registro del conjunto de registros. También se puede usar IsBOF junto con IsEOF para determinar si el conjunto de registros contiene registros o si está vacío. Inmediatamente después de llamar a Open, si el conjunto de registros no contiene registros, IsBOF devuelve un valor distinto de cero. Cuando se abre un conjunto de registros que tiene al menos un registro, el primer registro es el registro actual y IsBOF devuelve 0.

Si el primer registro es el registro actual y se llama a MovePrev, IsBOF devolverá un valor distinto de cero. Si IsBOF devuelve un valor distinto de cero y se llama a MovePrev, se produce un error. Si IsBOF devuelve un valor distinto de cero, el registro actual no está definido, y cualquier acción que requiera un registro actual producirá un error.

Ejemplo

En este ejemplo se usa IsBOF y IsEOF para detectar los límites de un conjunto de registros a medida que el código se desplaza por el conjunto de registros en ambas direcciones.

// Open a recordset; first record is current
// Open a recordset; first record is current
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if(rsCustSet.IsBOF())
   return;
   // The recordset is empty

// Scroll to the end of the recordset, past
// the last record, so no record is current
while (!rsCustSet.IsEOF())
   rsCustSet.MoveNext();

// Move to the last record
rsCustSet.MoveLast();

// Scroll to beginning of the recordset, before
// the first record, so no record is current
while(!rsCustSet.IsBOF())
   rsCustSet.MovePrev();

// First record is current again
rsCustSet.MoveFirst();

`CRecordset::IsDeleted`

Determina si se ha eliminado el registro actual.

BOOL IsDeleted() const;

Valor devuelto

Un valor distinto de cero si el conjunto de registros se coloca en un registro eliminado; de lo contrario, 0.

Comentarios

Si se desplaza a un registro y IsDeleted devuelve TRUE (un valor distinto de cero), deberá desplazarse a otro registro para poder realizar cualquier otra operación de conjunto de registros.

El resultado de IsDeleted depende de muchos factores, como el tipo del conjunto de registros, si el conjunto de registros se puede actualizar, si se ha especificado la opción CRecordset::skipDeletedRecords al abrir el conjunto de registros, si los paquetes de controladores han eliminado registros y si hay varios usuarios.

Para obtener más información sobre CRecordset::skipDeletedRecords y los paquetes de controladores, vea la función miembro Open.

Nota:

Si se ha implementado la captura masiva de filas, se desaconseja llamar a IsDeleted. En su lugar, llame a la función miembro GetRowStatus. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

`CRecordset::IsEOF`

Devuelve un valor distinto de cero si el conjunto de registros se ha colocado después del último registro. No hay registro actual.

BOOL IsEOF() const;

Valor devuelto

Un valor distinto de cero si el conjunto de registros no contiene registros o si el usuario se ha desplazado más allá del último registro; de lo contrario, 0.

Comentarios

Llame a esta función miembro a medida que se desplaza de un registro a otro para saber si ha ido más allá del último registro del conjunto de registros. También se puede usar IsEOF para determinar si el conjunto de registros contiene registros o si está vacío. Inmediatamente después de llamar a Open, si el conjunto de registros no contiene registros, IsEOF devuelve un valor distinto de cero. Cuando se abre un conjunto de registros que tiene al menos un registro, el primer registro es el registro actual y IsEOF devuelve 0.

Si el último registro es el registro actual cuando se llama a MoveNext, IsEOF devolverá un valor distinto de cero. Si IsEOF devuelve un valor distinto de cero y se llama a MoveNext, se produce un error. Si IsEOF devuelve un valor distinto de cero, el registro actual no está definido, y cualquier acción que requiera un registro actual producirá un error.

Ejemplo

Vea el ejemplo de IsBOF.

`CRecordset::IsFieldDirty`

Determina si el miembro de datos de campo especificado ha cambiado desde que se llamó a Edit o a AddNew.

BOOL IsFieldDirty(void* pv);

Parámetros

pv
Puntero al miembro de datos de campo cuyo estado desea comprobar, o NULL para determinar si alguno de los campos tiene modificaciones.

Valor devuelto

Un valor distinto de cero si el miembro de datos de campo especificado ha cambiado desde que se llamó a AddNew o a Edit; de lo contrario, 0.

Comentarios

Los datos de todos los miembros de datos de campos con modificaciones se transferirán al registro en el origen de datos cuando el registro actual se actualice mediante una llamada a la función miembro Update de CRecordset (después de una llamada a Edit o a AddNew).

Nota:

Esta función miembro no se puede usar en conjuntos de registros que usen la captura masiva de filas. Si ha implementado la captura masiva de filas, IsFieldDirty siempre devolverá FALSE y generará una aserción con errores. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

La llamada a IsFieldDirty restablecerá los efectos de las llamadas anteriores a SetFieldDirty, ya que se vuelve a evaluar el estado modificado del campo. En el caso de AddNew, si el valor del campo actual difiere del valor "pseudo-NULL", el estado del campo se establece como con modificaciones. En el caso de Edit, si el valor del campo difiere del valor almacenado en caché, el estado del campo se establece como con modificaciones.

IsFieldDirty se implementa a través de DoFieldExchange.

Para obtener más información sobre el marcador de modificado, vea Conjunto de registros: cómo actualizan registros los conjuntos de registros (ODBC).

`CRecordset::IsFieldNull`

Devuelve un valor distinto de cero si el campo especificado en el registro actual es NULL (no tiene ningún valor).

BOOL IsFieldNull(void* pv);

Parámetros

pv
Puntero al miembro de datos de campo cuyo estado desea comprobar, o NULL para determinar si alguno de los campos es NULL.

Valor devuelto

Un valor distinto de cero si el miembro de datos de campo especificado se marca como NULL; de lo contrario, 0.

Comentarios

Llame a esta función miembro para determinar si el miembro de datos de campo especificado de un conjunto de registros se ha marcado como NULL (en la terminología de bases de datos, NULL significa "sin valor"; no es lo mismo que NULL en C++). Si un miembro de datos de campo se marca como NULL, se interpreta como una columna del registro actual en la que no hay ningún valor.

Nota:

Esta función miembro no se puede usar en conjuntos de registros que usen la captura masiva de filas. Si ha implementado la captura masiva de filas, IsFieldNull siempre devolverá FALSE y generará una aserción con errores. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

IsFieldNull se implementa a través de DoFieldExchange.

`CRecordset::IsFieldNullable`

Devuelve un valor distinto de cero si el campo especificado en el registro actual se puede establecer en NULL (no tiene ningún valor).

BOOL IsFieldNullable(void* pv);

Parámetros

pv
Puntero al miembro de datos de campo cuyo estado desea comprobar, o NULL para determinar si alguno de los campos se puede establecer en un valor NULL.

Comentarios

Llame a esta función miembro para determinar si el miembro de datos de campo especificado "acepta valores NULL" (es decir, se puede establecer en un valor NULL; en C++, NULL no es lo mismo que NULL en la terminología de bases de datos, que significa "sin valor").

Nota:

Si ha implementado la captura masiva de filas, no puede llamar a IsFieldNullable. En su lugar, llame a la función miembro GetODBCFieldInfo para determinar si un campo se puede establecer en un valor NULL. Siempre se puede llamar a GetODBCFieldInfo, independientemente de si se ha implementado la captura masiva de filas. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

Un campo que no puede ser NULL debe tener un valor. Si intenta establecer un campo de este tipo en NULL al agregar o actualizar un registro, el origen de datos rechaza la adición o actualización y Update producirá una excepción. La excepción se produce cuando se llama a Update, no cuando se llama a SetFieldNull.

Si se usa NULL como primer argumento de la función, esta solo se aplicará a los campos outputColumn, no a los campos param. Por ejemplo, la llamada

SetFieldNull(NULL);

establecerá únicamente los campos outputColumn en NULL; los campos param no se verán afectados.

Para trabajar en los campos param, debe proporcionar la dirección real del campo param individual en el que quiera trabajar, como:

SetFieldNull(&m_strParam);

Esto significa que no se pueden establecer todos los campos param en NULL, cosa que sí es factible con los campos outputColumn.

IsFieldNullable se implementa a través de DoFieldExchange.

`CRecordset::IsOpen`

Determina si el conjunto de registros ya está abierto.

BOOL IsOpen() const;

Valor devuelto

Un valor distinto de cero si se ha llamado previamente a la función miembro Open o Requery del objeto de conjunto de registros y el conjunto de registros no se ha cerrado; de lo contrario, 0.

`CRecordset::m_hstmt`

Contiene un identificador de la estructura de datos de la instrucción ODBC, de tipo HSTMT, asociado al conjunto de registros.

Comentarios

Cada consulta a un origen de datos ODBC está asociada a un objeto HSTMT.

Precaución

No use m_hstmt antes de llamar a Open.

Por lo general, acceder a HSTMT directamente no es necesario, pero es posible que lo necesite para la ejecución directa de instrucciones SQL. La función miembro ExecuteSQL de la clase CDatabase proporciona un ejemplo de uso de m_hstmt.

`CRecordset::m_nFields`

Contiene el número de miembros de datos de campo de la clase del conjunto de registros; es decir, el número de columnas que el conjunto de registros ha seleccionado en el origen de datos.

Comentarios

El constructor de la clase de conjunto de registros debe inicializar m_nFields con el número correcto. Si no ha implementado la captura masiva de filas, ClassWizard escribe esta inicialización automáticamente cuando la usa para declarar la clase de conjunto de registros. También se puede escribir manualmente.

El marco usa este número para administrar la interacción entre los miembros de datos de campo y las columnas correspondientes del registro actual en el origen de datos.

Precaución

Este número debe corresponder al número de "columnas de salida" registradas en DoFieldExchange o en DoBulkFieldExchange después de una llamada a SetFieldType con el parámetro CFieldExchange::outputColumn.

Las columnas se pueden enlazar dinámicamente, como se explica en el artículo "Conjunto de registros: enlazar dinámicamente columnas de datos". Si lo hace, debe aumentar el número en m_nFields de forma que refleje el número de llamadas a funciones de RFX o RFX masivo en la función miembro DoFieldExchange o DoBulkFieldExchange de las columnas enlazadas dinámicamente.

Para obtener más información, vea los artículos Conjunto de registros: enlazar dinámicamente columnas de datos (ODBC) y Conjunto de registros: obtener registros de forma masiva (ODBC).

Ejemplo

Vea Intercambio de campos de registros: uso de RFX.

`CRecordset::m_nParams`

Contiene el número de miembros de datos de parámetros en la clase de conjunto de registros; es decir, el número de parámetros pasados con la consulta del conjunto de registros.

Comentarios

Si la clase de conjunto de registros tiene miembros de datos de parámetros, el constructor de la clase debe inicializar m_nParams con el número correcto. El valor predeterminado de m_nParams es 0. Si agrega miembros de datos de parámetros (algo que debe hacer manualmente), también debe agregar manualmente una inicialización en el constructor de clase para reflejar el número de parámetros (que debe ser como mínimo igual que el número de marcadores de posición " en la cadena m_strFilter o m_strSort).

El marco usa este número cuando parametriza la consulta del conjunto de registros.

Precaución

Este número debe corresponder al número de "parámetros" registrados en DoFieldExchange o en DoBulkFieldExchange después de una llamada a SetFieldType con un valor de parámetro de CFieldExchange::inputParam, CFieldExchange::param, CFieldExchange::outputParam o CFieldExchange::inoutParam.

Ejemplo

Vea los artículos Conjunto de registros: parametrización de un conjunto de registros (ODBC) e Intercambio de campos de registros: uso de RFX.

`CRecordset::m_pDatabase`

Contiene un puntero al objeto CDatabase a través del cual el conjunto de registros está conectado a un origen de datos.

Comentarios

Esta variable se establece de dos formas. Normalmente, se pasa un puntero a un objeto CDatabase ya conectado al construir el objeto de conjunto de registros. Si se pasa NULL en su lugar, CRecordset crea un objeto CDatabase automáticamente y lo conecta. En cualquier caso, CRecordset almacena el puntero en esta variable.

Por lo general, no es necesario usar directamente el puntero almacenado en m_pDatabase. Sin embargo, si escribe sus propias extensiones en CRecordset, puede que tenga que usarlo. Por ejemplo, es posible que necesite el puntero si inicia sus propias excepciones CDBException, o si necesita hacer algo con el mismo objeto CDatabase, como ejecutar transacciones, establecer tiempos de espera o llamar a la función miembro ExecuteSQL de la clase CDatabase para ejecutar instrucciones SQL directamente.

`CRecordset::m_strFilter`

Después de construir el objeto de conjunto de registros, pero antes de llamar a su función miembro Open, use este miembro de datos para almacenar un objeto CString que contiene una cláusula SQL WHERE.

Comentarios

El conjunto de registros usa esta cadena para restringir (o filtrar) los registros que se seleccionan durante la llamada a Open o a Requery. Esto resulta útil para seleccionar un subconjunto de registros, como "todos los vendedores de California" ("state = CA"). La sintaxis SQL ODBC de una cláusula WHERE es:

WHERE search-condition

No incluya la palabra clave WHERE en la cadena. El marco la suministra.

También puede parametrizar la cadena de filtro colocando marcadores de posición " en ella, declarando un miembro de datos de parámetros en la clase para cada marcador de posición y pasando parámetros al conjunto de registros en tiempo de ejecución. Esto permite crear el filtro en tiempo de ejecución. Para más información, vea Conjunto de registros: Parametrizar un conjunto de registros (ODBC).

Para obtener más información sobre las cláusulas SQL WHERE, vea SQL. Para obtener más información sobre cómo seleccionar y filtrar registros, vea Conjunto de registros: filtrar registros (ODBC).

Ejemplo

CCustomer rsCustSet(&m_dbCust);

// Set the filter
rsCustSet.m_strFilter = _T("L_Name = 'Flanders'");

// Run the filtered query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

`CRecordset::m_strSort`

Comentarios

El conjunto de registros usa esta cadena para ordenar los registros que se seleccionan durante la llamada a Open o a Requery. Puede usar esta característica para ordenar un conjunto de registros en una o varias columnas. La sintaxis SQL ODBC de una cláusula ORDER BY es:

ORDER BY sort-specification [, sort-specification]...

donde "sort-specification" es un entero o un nombre de columna. También puede especificar un orden ascendente o descendente (el orden es ascendente de forma predeterminada), anexando para ello "ASC" o "DESC" a la lista de columnas de la cadena de ordenación. Los registros seleccionados se ordenan primero por la primera columna indicada, después por la segunda, etc. Por ejemplo, puede solicitar un conjunto de registros "Clientes" por apellido y, a continuación, por nombre. El número de columnas que se pueden mostrar depende del origen de datos. Para obtener más información, vea Windows SDK.

No incluya la palabra clave ORDER BY en la cadena. El marco la suministra.

Para obtener más información sobre las cláusulas SQL, vea SQL. Para obtener más información sobre cómo ordenar registros, vea Conjunto de registros: ordenar registros (ODBC).

Ejemplo

CCustomer rsCustSet(&m_dbCust);

// Set the sort string
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");

// Run the sorted query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

`CRecordset::Move`

Mueve el puntero de registro actual dentro del conjunto de registros, ya sea hacia delante o hacia atrás.

virtual void Move(
    long nRows,
    WORD wFetchType = SQL_FETCH_RELATIVE);

Parámetros

nRows
Número de filas que se van a mover hacia delante o hacia atrás. Los valores positivos mueven hacia delante, hacia el final del conjunto de registros Los valores negativos se mueven hacia atrás, hacia el principio.

wFetchType
Determina el conjunto de filas que Move va a capturar. Para conocer más detalles, vea la sección Comentarios.

Comentarios

Si se pasa un valor de 0 en nRows, Move actualiza el registro actual; Move finalizará cualquier modo AddNew o Edit actual y restaurará el valor del registro actual antes de llamar a AddNew o a Edit.

Nota:

Al desplazarse por un conjunto de registros, no se pueden omitir los registros eliminados. Consulte CRecordset::IsDeleted para obtener más información. Cuando CRecordset se abre con la opción skipDeletedRecords establecida, Move se impone si el parámetro nRows es 0. Este comportamiento impide que se actualicen las filas que otras aplicaciones cliente que usan los mismos datos eliminan. Vea el parámetro dwOption en Open para obtener una descripción de skipDeletedRecords.

Move cambia la posición del conjunto de registros por conjuntos de filas. En función de los valores de nRows y wFetchType, Move captura el conjunto de filas adecuado y, a continuación, convierte el primer registro de ese conjunto de filas en el registro actual. Si no se ha implementado la captura masiva de filas, el tamaño del conjunto de filas siempre es 1. Al capturar un conjunto de filas, Move llama directamente a la función miembro CheckRowsetError para controlar los errores resultantes de la captura.

Según los valores que se pasen, Move equivale a otras funciones miembro CRecordset. En concreto, el valor de wFetchType puede indicar una función miembro más intuitiva y, a menudo, el método preferido para mover el registro actual.

En la siguiente tabla se enumeran los valores posibles para wFetchType, el conjunto de filas que Move capturará en función de wFetchType y de nRows, y cualquier función miembro equivalente correspondiente a wFetchType.

wFetchType	Conjunto de filas capturado	Función miembro equivalente
`SQL_FETCH_RELATIVE` (valor predeterminado)	Conjunto de filas que comienza `nRows` filas a partir de la primera fila del conjunto de filas actual.
`SQL_FETCH_NEXT`	El siguiente conjunto de filas; `nRows` se omite.	`MoveNext`
`SQL_FETCH_PRIOR`	El conjunto de filas anterior; `nRows` se omite.	`MovePrev`
`SQL_FETCH_FIRST`	Primer conjunto de filas del conjunto de registros; `nRows` se omite.	`MoveFirst`
`SQL_FETCH_LAST`	Último conjunto de filas completo del conjunto de registros; `nRows` se omite.	`MoveLast`
`SQL_FETCH_ABSOLUTE`	Si `nRows`> es 0, el conjunto de filas que comienza `nRows` filas a partir del inicio del conjunto de registros. Si `nRows`< es 0, el conjunto de filas que comienza `nRows` filas desde el final del conjunto de registros. Si `nRows` es = 0, se devuelve una condición de principio de archivo (BOF).	`SetAbsolutePosition`
`SQL_FETCH_BOOKMARK`	Conjunto de filas que comienza en la fila cuyo valor de marcador corresponde a `nRows`.	`SetBookmark`

Nota:

En el caso de los conjuntos de registros de solo avance, Move solo es válido con un valor de SQL_FETCH_NEXT para wFetchType.

Precaución

Al llamar a Move se produce una excepción si el conjunto de registros no tiene registros. Para determinar si el conjunto de registros tiene registros, llame a IsBOF y a IsEOF.

Nota:

Si se ha desplazado más allá del principio o final del conjunto de registros (IsBOF o IsEOF devuelve un valor distinto de cero), llamar a una función Move posiblemente producirá una excepción CDBException. Por ejemplo, si IsEOF devuelve un valor distinto de cero y IsBOF no, MoveNext producirá una excepción, pero MovePrev no.

Nota:

Si llama a Move mientras el registro actual se actualiza o se agrega, las actualizaciones se pierden sin previo aviso.

Para obtener más información sobre la navegación por el conjunto de registros, vea los artículos Conjunto de registros: desplazamiento (ODBC) y Conjunto de registros: marcadores y posiciones absolutas (ODBC). Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC). Para obtener información relacionada, vea la función de API ODBC SQLExtendedFetch en Windows SDK.

Ejemplo

// rs is a CRecordset or a CRecordset-derived object

// Change the rowset size to 5
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// Move to the first record in the recordset
rs.MoveFirst();

// Move to the sixth record
rs.Move(5);
// Other equivalent ways to move to the sixth record:
rs.Move(6, SQL_FETCH_ABSOLUTE);
rs.SetAbsolutePosition(6);
// In this case, the sixth record is the first record in the next rowset,
// so the following are also equivalent:
rs.MoveFirst();
rs.Move(1, SQL_FETCH_NEXT);

rs.MoveFirst();
rs.MoveNext();

`CRecordset::MoveFirst`

Convierte el primer registro en el primer conjunto de filas del registro actual.

void MoveFirst();

Comentarios

Independientemente de si se ha implementado la captura masiva de filas, siempre será el primer registro del conjunto de registros.

No es necesario llamar a MoveFirst inmediatamente después de abrir el conjunto de registros. En ese momento, el primer registro (si existe) es automáticamente el registro actual.

Nota:

Esta función miembro no es válida en los conjuntos de registros de solo avance.

Nota:

Al desplazarse por un conjunto de registros, no se pueden omitir los registros eliminados. Consulte la función miembro IsDeleted para obtener información más detallada.

Precaución

Al llamar a cualquiera de las funciones Move, se produce una excepción si el conjunto de registros no tiene registros. Para determinar si el conjunto de registros tiene registros, llame a IsBOF y a IsEOF.

Nota:

Si llama a cualquiera de las funciones Move mientras el registro actual se actualiza o se agrega, las actualizaciones se pierden sin previo aviso.

Ejemplo

Vea el ejemplo de IsBOF.

`CRecordset::MoveLast`

Convierte el primer registro en el último conjunto de filas completo del registro actual.

void MoveLast();

Comentarios

Si no se ha implementado la captura masiva de filas, el conjunto de registros tiene un tamaño de conjunto de filas de 1, por lo que MoveLast pasa al último registro del conjunto de registros.

Nota:

Esta función miembro no es válida en los conjuntos de registros de solo avance.

Nota:

Al desplazarse por un conjunto de registros, no se pueden omitir los registros eliminados. Consulte la función miembro IsDeleted para obtener información más detallada.

Precaución

Nota:

Si llama a cualquiera de las funciones Move mientras el registro actual se actualiza o se agrega, las actualizaciones se pierden sin previo aviso.

Ejemplo

Vea el ejemplo de IsBOF.

`CRecordset::MoveNext`

Convierte el primer registro en el siguiente conjunto de filas del registro actual.

void MoveNext();

Comentarios

Si no se ha implementado la captura masiva de filas, el conjunto de registros tiene un tamaño de conjunto de filas de 1, por lo que MoveNext avanza al siguiente registro.

Nota:

Al desplazarse por un conjunto de registros, no se pueden omitir los registros eliminados. Consulte la función miembro IsDeleted para obtener información más detallada.

Precaución

Nota:

También se recomienda llamar a IsEOF antes de llamar a MoveNext. Por ejemplo, si se ha desplazado más allá del final del conjunto de registros, IsEOF devolverá un valor distinto de cero; una llamada posterior a MoveNext produciría una excepción.

Nota:

Si llama a cualquiera de las funciones Move mientras el registro actual se actualiza o se agrega, las actualizaciones se pierden sin previo aviso.

Ejemplo

Vea el ejemplo de IsBOF.

`CRecordset::MovePrev`

Convierte el primer registro en el conjunto de filas anterior del registro actual.

void MovePrev();

Comentarios

Si no se ha implementado la captura masiva de filas, el conjunto de registros tiene un tamaño de conjunto de filas de 1, por lo que MovePrev avanza al registro anterior.

Nota:

Esta función miembro no es válida en los conjuntos de registros de solo avance.

Nota:

Al desplazarse por un conjunto de registros, no se pueden omitir los registros eliminados. Consulte la función miembro IsDeleted para obtener información más detallada.

Precaución

Nota:

También se recomienda llamar a IsBOF antes de llamar a MovePrev. Por ejemplo, si se ha desplazado por delante del inicio del conjunto de registros, IsBOF devolverá un valor distinto de cero; una llamada posterior a MovePrev produciría una excepción.

Nota:

Si llama a cualquiera de las funciones Move mientras el registro actual se actualiza o se agrega, las actualizaciones se pierden sin previo aviso.

Ejemplo

Vea el ejemplo de IsBOF.

`CRecordset::OnSetOptions`

Se llama a este método para establecer opciones (usadas al seleccionar) de la instrucción ODBC especificada.

virtual void OnSetOptions(HSTMT hstmt);

Parámetros

hstmt
HSTMT de la instrucción ODBC cuyas opciones se van a establecer.

Comentarios

Llame a OnSetOptions para establecer opciones (usadas al seleccionar) de la instrucción ODBC especificada. El marco llama a esta función miembro para establecer las opciones iniciales del conjunto de registros. OnSetOptions determina si el origen de datos admite cursores desplazables y la simultaneidad de cursores y establece las opciones del conjunto de registros en consecuencia (mientras que OnSetOptions se usa en las operaciones de selección, OnSetUpdateOptions se usa en las operaciones de actualización).

Invalide OnSetOptions para establecer opciones específicas del controlador o del origen de datos. Por ejemplo, si el origen de datos permite abrir elementos con acceso exclusivo, puede invalidar OnSetOptions para aprovechar esa capacidad.

Para obtener más información sobre los cursores, vea ODBC.

`CRecordset::OnSetUpdateOptions`

Se llama a este método para establecer opciones (usadas al actualizar) de la instrucción ODBC especificada.

virtual void OnSetUpdateOptions(HSTMT hstmt);

Parámetros

hstmt
HSTMT de la instrucción ODBC cuyas opciones se van a establecer.

Comentarios

Llame a OnSetUpdateOptions para establecer opciones (usadas al actualizar) de la instrucción ODBC especificada. El marco llama a esta función miembro después de crear un elemento HSTMT para actualizar los registros de un conjunto de registros (mientras que OnSetOptions se usa en las operaciones de selección, OnSetUpdateOptions se usa en las operaciones de actualización). OnSetUpdateOptions determina si el origen de datos admite cursores desplazables y la simultaneidad de cursores y establece las opciones del conjunto de registros en consecuencia.

Invalide OnSetUpdateOptions para establecer opciones de una instrucción ODBC antes de que esa instrucción se use para acceder a una base de datos.

Para obtener más información sobre los cursores, vea ODBC.

`CRecordset::Open`

Abre el conjunto de registros recuperando la tabla o realizando la consulta que el conjunto de registros representa.

virtual BOOL Open(
    UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE,
    LPCTSTR lpszSQL = NULL,
    DWORD dwOptions = none);

Parámetros

nOpenType
Acepte el valor predeterminado (AFX_DB_USE_DEFAULT_TYPE) o use uno de los siguientes valores de enum OpenType:

CRecordset::dynaset Un conjunto de registros con desplazamiento bidireccional. La pertenencia y el orden de los registros se determinan cuando se abre el conjunto de registros, pero los cambios realizados por otros usuarios en los valores de datos son visibles después de una operación de búsqueda. Los dynasets también se conocen como conjuntos de registros conjunto controlados por conjuntos de claves.
CRecordset::snapshot Un conjunto de registros estático con desplazamiento bidireccional. La pertenencia y el orden de los registros se determinan cuando se abre el conjunto de registros. La captura de un registro determina los valores de datos. Los cambios realizados por otros usuarios no son visibles hasta que no se cierra y se vuelve a abrir el conjunto de registros.
CRecordset::dynamic Un conjunto de registros con desplazamiento bidireccional. Los cambios realizados por otros usuarios en la pertenencia, el orden y los valores de datos son visibles después de una operación de recuperación de cambios. Muchos controladores ODBC no admiten este tipo de conjunto de registros.
CRecordset::forwardOnly Un conjunto de registros de solo lectura con desplazamiento solo de avance.

En CRecordset, el valor predeterminado es CRecordset::snapshot. El mecanismo de valor predeterminado permite que los asistentes de Visual C++ interactúen con CRecordset de ODBC y CDaoRecordset de DAO, que tienen valores predeterminados diferentes.

Para obtener más información sobre estos tipos de conjunto de registros, vea Conjunto de registros (ODBC). Para obtener información relacionada, vea la sección sobre el uso de cursores de bloque y desplazables en Windows SDK.

Precaución

Si el tipo solicitado no se admite, el marco de trabajo produce una excepción.

lpszSQL
Puntero de cadena que contiene uno de los elementos siguientes:

Un puntero NULL.
Nombre de una tabla.
Una instrucción SQL SELECT (opcionalmente, con una cláusula SQL WHERE o ORDER BY).
Una instrucción CALL que especifica el nombre de una consulta predefinida (procedimiento almacenado). Procure no insertar un espacio en blanco entre la llave y la palabra clave CALL.

Para obtener más información sobre esta cadena, vea la tabla y la descripción del rol de ClassWizard en la sección Comentarios.

Nota:

El orden de las columnas del conjunto de resultados debe coincidir con el orden de las llamadas de función RFX o RFX masivo en la invalidación de la función DoFieldExchange o DoBulkFieldExchange.

dwOptions
Máscara de bits que puede especificar una combinación de los valores que se muestran a continuación. Algunas de estas opciones son mutuamente excluyentes. El valor predeterminado es none.

CRecordset::none No hay opciones establecidas. Este valor del parámetro es mutuamente excluyente con todos los demás valores. De forma predeterminada, el conjunto de registros se puede actualizar con Edit o con Delete, y permite anexar nuevos registros con AddNew. La posibilidad de actualización depende del origen de datos y de la opción de nOpenType que se especifique. La optimización de adiciones masivas no está disponible. La captura masiva de filas no se implementará. Los registros eliminados no se omitirán al navegar por el conjunto de registros. Los marcadores no están disponibles. Se implementa la comprobación automática de campos modificados.
CRecordset::appendOnly Ni Edit ni Delete están permitidos en el conjunto de registros. Solo permite AddNew. Esta opción es mutuamente excluyente con CRecordset::readOnly.
CRecordset::readOnly El conjunto de registros se abre como de solo lectura. Esta opción es mutuamente excluyente con CRecordset::appendOnly.
CRecordset::optimizeBulkAdd Se usa una instrucción SQL preparada para optimizar la adición de muchos registros a la vez. Solo se aplica si no se está utilizando la función de API ODBC SQLSetPos para actualizar el conjunto de registros. La primera actualización determina qué campos se marcan como modificados. Esta opción es mutuamente excluyente con CRecordset::useMultiRowFetch.
CRecordset::useMultiRowFetch Implementa la captura masiva de filas para permitir la recuperación de varias filas en una misma operación de búsqueda. Se trata de una característica avanzada diseñada para mejorar el rendimiento; sin embargo, ClassWizard no admite el intercambio masivo de campos de registros. Esta opción es mutuamente excluyente con CRecordset::optimizeBulkAdd. Si se especifica CRecordset::useMultiRowFetch, la opción CRecordset::noDirtyFieldCheck se activará automáticamente (el almacenamiento en búfer doble no estará disponible); en los conjuntos de registros de solo avance, la opción CRecordset::useExtendedFetch se activará automáticamente. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).
CRecordset::skipDeletedRecords Omite todos los registros eliminados al navegar por el conjunto de registros. Esto ralentiza el rendimiento en ciertas búsquedas relativas. Esta opción no es válida en los conjuntos de registros de solo avance. Si se llama a Move con el parámetro nRows establecido en 0 y la opción CRecordset::skipDeletedRecords configurada, Move se impondrá. CRecordset::skipDeletedRecords es similar a los paquetes de controladores, lo que significa que las filas eliminadas se quitan del conjunto de registros. Sin embargo, si el controlador empaqueta registros, solo se omitirán los registros que elimine; no se omitirán los registros eliminados por otros usuarios mientras el conjunto de registros está abierto. CRecordset::skipDeletedRecords omitirá las filas eliminadas por otros usuarios.
CRecordset::useBookmarks Se pueden usar marcadores en el conjunto de registros, si esto es posible. Los marcadores ralentizan la recuperación de datos pero mejoran el rendimiento de la navegación de datos. No es válida en conjuntos de registros solo hacia delante. Para obtener más información, vea Conjunto de registros: marcadores y posiciones absolutas (ODBC).
CRecordset::noDirtyFieldCheck Desactiva la comprobación automática de campos modificados (almacenamiento en búfer doble). Esto mejorará el rendimiento; sin embargo, para marcar manualmente los campos como modificados se debe llamar a las funciones miembro SetFieldDirty y SetFieldNull. El almacenamiento en búfer doble de la clase CRecordset es similar al almacenamiento en búfer doble de la clase CDaoRecordset. Sin embargo, en CRecordset no se puede habilitar el almacenamiento en búfer doble en campos individuales; hay que habilitarlo o deshabilitarlo en todos los campos. Si se especifica la opción CRecordset::useMultiRowFetch, CRecordset::noDirtyFieldCheck se activará automáticamente; sin embargo, SetFieldDirty y SetFieldNull no se pueden utilizar en conjuntos de registros que implementan la captura masiva de filas.
CRecordset::executeDirect No use una instrucción SQL preparada. Para mejorar el rendimiento, especifique esta opción si nunca se va a llamar a la función miembro Requery.
CRecordset::useExtendedFetch Implementa SQLExtendedFetch en lugar de SQLFetch. Está diseñado para implementar la obtención masiva de filas en conjuntos de registros solo hacia delante. Si se especifica la opción CRecordset::useMultiRowFetch en un conjunto de registros de solo avance, CRecordset::useExtendedFetch se activará automáticamente.
CRecordset::userAllocMultiRowBuffers El usuario asignará búferes de almacenamiento para los datos. Use esta opción con CRecordset::useMultiRowFetch si quiere asignar su propio almacenamiento; de lo contrario, el marco asignará automáticamente el almacenamiento necesario. Para más información, consulte Conjunto de registros: obtener registros de forma masiva (ODBC). Especificar CRecordset::userAllocMultiRowBuffers sin especificar CRecordset::useMultiRowFetch da como resultado una aserción errónea.

Valor devuelto

Un valor distinto de cero si el objeto CRecordset se ha abierto correctamente; de lo contrario, es 0 si CDatabase::Open (si se le llama) devuelve 0.

Comentarios

Se debe llamar a esta función miembro para ejecutar la consulta definida por el conjunto de registros. Antes de llamar a Open, se debe crear el objeto de conjunto de registros.

La conexión de este conjunto de registros con el origen de datos depende de cómo se cree el conjunto de registros antes de llamar a Open. Si se pasa al constructor del conjunto de registros un objeto CDatabase que no ha estado conectado al origen de datos, esta función miembro usa GetDefaultConnect para intentar abrir el objeto de base de datos. Si se pasa NULL al constructor del conjunto de registros, el constructor crea un objeto CDatabase, y Open intenta conectar el objeto de base de datos. Para obtener detalles sobre cómo cerrar el conjunto de registros y la conexión en estas circunstancias variables, vea Close.

Nota:

El acceso a un origen de datos mediante un objeto CRecordset siempre es compartido. A diferencia de la clase CDaoRecordset, un objeto CRecordset no se puede usar para abrir un origen de datos con acceso exclusivo.

Cuando se llama a Open, una consulta (normalmente, una instrucción SQL SELECT) selecciona los registros según los criterios que se muestran en la tabla siguiente.

Valor del parámetro `lpszSQL`	Los registros seleccionados están determinados por	Ejemplo
`NULL`	La cadena devuelta por `GetDefaultSQL`.
Nombre de tabla SQL	Todas las columnas de la lista de tablas de `DoFieldExchange` o `DoBulkFieldExchange`.	`"Customer"`
Nombre de la consulta (procedimiento almacenado) predefinida	Las columnas de la consulta cuya devolución se ha definido.	`"{call OverDueAccts}"`
`SELECT` lista de columnas `FROM` lista de tablas	Las columnas especificadas de las tablas indicadas.	`"SELECT CustId, CustName FROM` `Customer"`

Precaución

No inserte espacios en blanco adicionales en la cadena SQL. Por ejemplo, si inserta un espacio en blanco entre la llave y la palabra clave CALL, MFC interpretará incorrectamente la cadena SQL como un nombre de tabla y la incorporará a una instrucción SELECT, lo que hará que se produzca una excepción. Del mismo modo, si la consulta predefinida usa un parámetro de salida, no inserte un espacio en blanco entre la llave y el símbolo ''. Por último, no debe insertar espacios en blanco antes de la llave en una CALL instrucción o antes de la SELECT palabra clave en una SELECT instrucción .

El procedimiento habitual consiste en pasar NULL a Open; en este caso, Open llama a GetDefaultSQL. Si se está utilizando una clase CRecordset derivada, GetDefaultSQL proporciona el nombre o los nombres de tabla especificados en ClassWizard. Se puede especificar otra información en el parámetro lpszSQL.

Independientemente del valor que se pase, Open construye una cadena SQL final para la consulta (la cadena puede tener anexadas cláusulas SQL WHERE y ORDER BY a la cadena lpszSQL que se pasó) y, después, ejecuta la consulta. Para examinar la cadena construida hay que llamar a GetSQL después de llamar a Open. Para obtener más detalles sobre cómo el conjunto de registros crea una instrucción SQL y selecciona registros, vea Conjunto de registros: cómo actualizan registros los conjuntos de registros (ODBC).

Los miembros de datos de campo de la clase de conjunto de registros están enlazados a las columnas de los datos seleccionados. Si se devuelve algún registro, el primer registro se convierte en el registro actual.

Si se desea establecer opciones para el conjunto de registros, como un filtro o una ordenación, deben especificarse después de crear el objeto de conjunto de registros, pero antes de llamar a Open. Si desea actualizar los registros del conjunto de registros una vez que este se ha abierto, llame a Requery.

Para obtener más información, incluidos ejemplos adicionales, vea Conjunto de registros (ODBC), Conjunto de registros: cómo actualizan registros los conjuntos de registros (ODBC) y Conjunto de registros: crear y cerrar conjuntos de registros (ODBC).

Ejemplo

En los ejemplos de código siguientes se muestran distintas formas de llamar a Open.

// rsSnap, rsLName, and rsDefault are CRecordset or CRecordset-derived 
// objects

// Open rs using the default SQL statement, implement bookmarks, and turn 
// off automatic dirty field checking
rsSnap.Open(CRecordset::snapshot, NULL, CRecordset::useBookmarks |
   CRecordset::noDirtyFieldCheck);

// Pass a complete SELECT statement and open as a dynaset
rsLName.Open(CRecordset::dynaset, _T("Select L_Name from Customer"));

// Accept all defaults
rsDefault.Open();

`CRecordset::RefreshRowset`

Actualiza los datos y el estado de una fila del conjunto de filas actual.

void RefreshRowset(
    WORD wRow,
    WORD wLockType = SQL_LOCK_NO_CHANGE);

Parámetros

wRow
Posición, según un índice de base 1, de una fila del conjunto de filas actual. Este valor puede oscilar entre 0 y el tamaño del conjunto de filas.

wLockType
Valor que indica cómo bloquear la fila después de actualizarla. Para conocer más detalles, vea la sección Comentarios.

Comentarios

Si se pasa un valor de cero para wRow, se actualizarán todas las filas del conjunto de filas.

Para usar RefreshRowset, se debe haber implementado la captura masiva de filas especificando la opción CRecordset::useMulitRowFetch en la función miembro Open.

RefreshRowset llama a la función de API ODBC SQLSetPos. El parámetro wLockType especifica el estado de bloqueo de la fila después de que SQLSetPos se haya ejecutado. En la siguiente tabla se describen los posibles valores de wLockType.

wLockType	Descripción
`SQL_LOCK_NO_CHANGE` (valor predeterminado)	El controlador o el origen de datos garantiza que la fila está en el mismo estado bloqueado o desbloqueado que antes de que se llamara a `RefreshRowset`.
`SQL_LOCK_EXCLUSIVE`	El controlador o el origen de datos bloquea la fila exclusivamente. No todos los orígenes de datos admiten este tipo de bloqueo.
`SQL_LOCK_UNLOCK`	El controlador o el origen de datos desbloquea la fila. No todos los orígenes de datos admiten este tipo de bloqueo.

Consulte Windows SDK para obtener más información sobre SQLSetPos. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

`CRecordset::Requery`

Recompila (actualiza) un conjunto de registros.

virtual BOOL Requery();

Valor devuelto

Un valor distinto de cero si el conjunto de registros se recompiló correctamente; de lo contrario, 0.

Comentarios

Si se devuelve algún registro, el primer registro se convierte en el registro actual.

Para que el conjunto de registros refleje las adiciones y eliminaciones que usted u otros usuarios hayan realizado en el origen de datos, el conjunto de registros se debe recompilar mediante una llamada a Requery. Si el conjunto de registros es un conjunto de registros dinámicos, refleja automáticamente las actualizaciones (pero no las adiciones) que usted u otros usuarios hayan realizado en sus registros existentes. Si el conjunto de registros es una instantánea, se debe llamar a Requery para reflejar las modificaciones realizadas por otros usuarios, así como las adiciones y eliminaciones.

En un conjunto de registros dinámicos o una instantánea, llame a Requery cada vez que quiera recompilar el conjunto de registros mediante un nuevo filtro u ordenación, o bien nuevos valores de parámetro. Establezca la propiedad de nuevo filtro u ordenación asignando nuevos valores a m_strFilter y a m_strSort antes de llamar a Requery. Establezca nuevos parámetros asignando nuevos valores a los miembros de datos de parámetros antes de llamar a Requery. Si las cadenas de filtro y ordenación no cambian, la consulta se puede reutilizar, lo que mejora el rendimiento.

Si se produce un error en el intento de recompilación del conjunto de registros, se cierra el conjunto de registros. Antes de llamar a Requery, puede determinar si se puede volver a consultar el conjunto de registros llamando a la función miembro CanRestart. CanRestart no garantiza que Requery se realice correctamente.

Precaución

Llame a Requery solo después de haber llamado a Open.

Ejemplo

En este ejemplo se recompila un conjunto de registros para aplicar un criterio de ordenación diferente.

CCustomer rsCustSet(&m_dbCust);

// Open the recordset
rsCustSet.Open();

// Use the recordset ...

// Set the sort order and Requery the recordset
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");
if (!rsCustSet.CanRestart())
return;    // Unable to requery

if (!rsCustSet.Requery())
// Requery failed, so take action
AfxMessageBox(_T("Requery failed!"));

`CRecordset::SetAbsolutePosition`

Coloca el conjunto de registros en el registro correspondiente al número de registro especificado.

void SetAbsolutePosition(long nRows);

Parámetros

nRows
Posición ordinal, según un índice de base 1, del registro actual del conjunto de registros.

Comentarios

SetAbsolutePosition mueve el puntero de registro actual en función de esta posición ordinal.

Nota:

Esta función miembro no es válida en los conjuntos de registros de solo avance.

En los conjuntos de registros ODBC, un valor de posición absoluta de 1 hace referencia al primer registro del conjunto de registros y un valor de 0, a la posición del principio del archivo (BOF).

También se pueden pasar valores negativos a SetAbsolutePosition. En tal caso, la posición del conjunto de registros se evalúa desde el final del conjunto de registros. Por ejemplo, SetAbsolutePosition( -1 ) mueve el puntero de registro actual al último registro del conjunto de registros.

Nota:

La posición absoluta no está pensada para usarse como número de registro suplente. Los marcadores siguen siendo la forma recomendada de conservar una posición determinada y volver a ella, ya que la posición de un registro cambia cuando se eliminan los registros anteriores. Además, no se puede tener la certeza de que un registro determinado vaya a tener la misma posición absoluta si el conjunto de registros se vuelve a crear, porque el orden de los registros individuales dentro de un conjunto de registros no está garantizado, a menos que se cree con una instrucción SQL usando una cláusula ORDER BY.

Para obtener más información sobre la navegación por el conjunto de registros y los marcadores, vea los artículos Conjunto de registros: desplazamiento (ODBC) y Conjunto de registros: marcadores y posiciones absolutas (ODBC).

`CRecordset::SetBookmark`

Coloca el conjunto de registros en el registro que contiene el marcador especificado.

void SetBookmark(const CDBVariant& varBookmark);

Parámetros

varBookmark
Referencia a un objeto CDBVariant que contiene el valor de marcador de un registro específico.

Comentarios

Nota:

Si no se admiten marcadores o no están disponibles, la llamada a SetBookmark producirá una excepción. Los marcadores no se admiten en conjuntos de registros de solo avance.

Para recuperar primero el marcador del registro actual, llame a GetBookmark, que guarda el valor de marcador en un objeto CDBVariant. Más adelante, puede volver a ese registro llamando a SetBookmark mediante el valor de marcador guardado.

Nota:

Después de determinadas operaciones de conjunto de registros, conviene comprobar la persistencia del marcador antes de llamar a SetBookmark. Por ejemplo, si se recupera un marcador con GetBookmark y, luego, se llama a Requery, es posible que el marcador ya no sea válido. Llame a CDatabase::GetBookmarkPersistence para comprobar si puede llamar a SetBookmark de forma segura.

`CRecordset::SetFieldDirty`

Marca un miembro de datos de campo del conjunto de registros como modificado o sin cambios.

void SetFieldDirty(void* pv, BOOL bDirty = TRUE);

Parámetros

pv
Contiene la dirección de un miembro de datos de campo en el conjunto de registros o NULL. Si es NULL, se marcan todos los miembros de datos de campo del conjunto de registros (en C++, NULL no es lo mismo que NULL en la terminología de bases de datos, que significa "sin valor").

bDirty
TRUE si el miembro de datos del campo se va a marcar como "con modificaciones". De lo contrario, FALSE si el miembro de datos de campo se va a marcar como "sin modificaciones".

Comentarios

Marcar los campos como sin modificaciones hace que esos campos no se actualicen, lo cual genera menos tráfico SQL.

Nota:

Esta función miembro no se puede usar en conjuntos de registros que usen la captura masiva de filas. Si se ha implementado la captura masiva de filas, SetFieldDirty generará una aserción con errores. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

El marco marca los miembros de datos de campo modificados para asegurarse de que se escribirán en el registro en el origen de datos mediante el mecanismo de intercambio de campos de registro (RFX). Cuando se cambia el valor de un campo, dicho campo se suele establecer como con modificaciones de manera automática, por lo que el usuario rara vez tendrá que llamar a SetFieldDirty por sí mismo, si bien es posible que quiera asegurarse de que las columnas se van a actualizar expresamente o se van a insertar independientemente del valor contenido en el miembro de datos del campo.

Precaución

Llame a esta función miembro solo después de haber llamado a Edit o a AddNew.

Si se usa NULL como primer argumento de la función, esta solo se aplicará a los campos outputColumn, no a los campos param. Por ejemplo, la llamada

SetFieldNull(NULL);

establecerá únicamente los campos outputColumn en NULL; los campos param no se verán afectados.

Para trabajar en los campos param, debe proporcionar la dirección real del campo param individual en el que quiera trabajar, como:

SetFieldNull(&m_strParam);

Esto significa que no se pueden establecer todos los campos param en NULL, cosa que sí es factible con los campos outputColumn.

`CRecordset::SetFieldNull`

Marca un miembro de datos de campo del conjunto de registros como NULL (es decir, sin valor) o como distinto de NULL.

void SetFieldNull(void* pv, BOOL bNull = TRUE);

Parámetros

pv
Contiene la dirección de un miembro de datos de campo en el conjunto de registros o NULL. Si es NULL, se marcan todos los miembros de datos de campo del conjunto de registros (en C++, NULL no es lo mismo que NULL en la terminología de bases de datos, que significa "sin valor").

bNull
Un valor distinto de cero si el miembro de datos de campo se marca como que no tiene ningún valor (NULL). De lo contrario, 0 si el miembro de datos de campo se va a marcar como no NULL.

Comentarios

Cuando se agrega un registro nuevo a un conjunto de registros, todos los miembros de datos de campo se establecen inicialmente en un valor NULL y se marcan como "con modificaciones". Cuando se recupera un registro de un origen de datos, sus columnas ya tienen valores o bien son NULL.

Nota:

No llame a esta función miembro en los conjuntos de registros que usen la captura masiva de filas. Si se ha implementado la captura masiva de filas, una llamada a SetFieldNull generará una aserción con errores. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

Si desea designar un campo del registro actual específicamente para no tener un valor, llame a SetFieldNull con bNull establecido en TRUE para marcarlo como NULL. Si un campo se marcó previamente como NULL y ahora le quiere asignar un valor, establezca su nuevo valor. No es necesario quitar la marca NULL con SetFieldNull. Para saber si un campo puede ser NULL, llame a IsFieldNullable.

Precaución

Llame a esta función miembro solo después de haber llamado a Edit o a AddNew.

Si se usa NULL como primer argumento de la función, esta solo se aplicará a los campos outputColumn, no a los campos param. Por ejemplo, la llamada

SetFieldNull(NULL);

establecerá únicamente los campos outputColumn en NULL; los campos param no se verán afectados.

Para trabajar en los campos param, debe proporcionar la dirección real del campo param individual en el que quiera trabajar, como:

SetFieldNull(&m_strParam);

Esto significa que no se pueden establecer todos los campos param en NULL, cosa que sí es factible con los campos outputColumn.

Nota:

Al establecer parámetros en NULL, una llamada a SetFieldNull antes de que se abra el conjunto de registros da como resultado una aserción. En tal caso, llame a SetParamNull.

SetFieldNull se implementa a través de DoFieldExchange.

`CRecordset::SetLockingMode`

Establece el modo de bloqueo en bloqueo "optimista" (valor predeterminado) o "pesimista". Determina cómo se bloquean los registros para las actualizaciones.

void SetLockingMode(UINT nMode);

Parámetros

nMode
Contiene uno de los siguientes valores de enum LockMode:

optimistic El bloqueo optimista bloquea el registro que se está actualizando únicamente durante la llamada a Update.
pessimistic El bloqueo pesimista bloquea el registro en cuanto se llama a Edit y lo mantiene bloqueado hasta que la llamada a Update finaliza o el usuario se traslada a otro registro.

Comentarios

Llame a esta función miembro si necesita especificar cuál de las dos estrategias de bloqueo de registros usa el conjunto de registros para las actualizaciones. De forma predeterminada, el modo de bloqueo de un conjunto de registros es optimistic. Puede cambiarlo a una estrategia de bloqueo pessimistic, más precavida. Llame a SetLockingMode después de construir y abrir el objeto de conjunto de registros, pero antes de llamar a Edit.

`CRecordset::SetParamNull`

Marca un parámetro como NULL (es decir, sin valor) o como distinto de NULL.

void SetParamNull(
    int nIndex,
    BOOL bNull = TRUE);

Parámetros

nIndex
Índice de base cero del parámetro.

bNull
Si es TRUE (valor predeterminado), el parámetro se marca como NULL. De lo contrario, el parámetro se marca como distinto de NULL.

Comentarios

A diferencia de SetFieldNull, se puede llamar a SetParamNull antes de que abrir el conjunto de registros.

SetParamNull se suele usar con consultas predefinidas (procedimientos almacenados).

`CRecordset::SetRowsetCursorPosition`

Mueve el cursor a una fila del conjunto de filas actual.

void SetRowsetCursorPosition(WORD wRow, WORD wLockType = SQL_LOCK_NO_CHANGE);

Parámetros

wRow
Posición, según un índice de base 1, de una fila del conjunto de filas actual. Este valor puede oscilar entre 1 y el tamaño del conjunto de filas.

wLockType
Valor que indica cómo bloquear la fila después de actualizarla. Para conocer más detalles, vea la sección Comentarios.

Comentarios

Al implementar la captura masiva de filas, los conjuntos de filas recuperan registros, donde el primer registro del conjunto de filas capturado es el registro actual. Llame a SetRowsetCursorPosition para designar otro registro del conjunto de filas como registro actual. Por ejemplo, puede combinar SetRowsetCursorPosition con la función miembro GetFieldValue para recuperar dinámicamente los datos de cualquier registro del conjunto de registros.

Para usar SetRowsetCursorPosition, se debe haber implementado la captura masiva de filas especificando la opción CRecordset::useMultiRowFetch en el parámetro dwOptions de la función miembro Open.

SetRowsetCursorPosition llama a la función de API ODBC SQLSetPos. El parámetro wLockType especifica el estado de bloqueo de la fila después de que SQLSetPos se haya ejecutado. En la siguiente tabla se describen los posibles valores de wLockType.

`wLockType`	Descripción
`SQL_LOCK_NO_CHANGE` (valor predeterminado)	El controlador o el origen de datos garantiza que la fila está en el mismo estado bloqueado o desbloqueado que antes de que se llamara a `SetRowsetCursorPosition`.
`SQL_LOCK_EXCLUSIVE`	El controlador o el origen de datos bloquea la fila exclusivamente. No todos los orígenes de datos admiten este tipo de bloqueo.
`SQL_LOCK_UNLOCK`	El controlador o el origen de datos desbloquea la fila. No todos los orígenes de datos admiten este tipo de bloqueo.

Consulte Windows SDK para obtener más información sobre SQLSetPos. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

`CRecordset::SetRowsetSize`

Especifica el número de registros que desea recuperar durante una captura.

virtual void SetRowsetSize(DWORD dwNewRowsetSize);

Parámetros

dwNewRowsetSize
Número de filas que se van a recuperar durante una captura determinada.

Comentarios

Esta función miembro virtual especifica cuántas filas quiere recuperar en una misma captura al usar la captura masiva de filas. Para implementar la captura masiva de filas, se debe establecer la opción CRecordset::useMultiRowFetch en el parámetro dwOptions de la función miembro Open.

Nota:

Si se llama a SetRowsetSize sin implementar la captura masiva de filas, se producirá una aserción con errores.

Llame a SetRowsetSize antes de llamar a Open para establecer inicialmente el tamaño del conjunto de filas del conjunto de registros. El tamaño predeterminado del conjunto de filas cuando se implementa la captura masiva de filas es 25.

Nota:

Tenga precaución al llamar a SetRowsetSize. Si va a asignar almacenamiento manualmente para los datos (según lo especificado por la opción CRecordset::userAllocMultiRowBuffers del parámetro dwOptions en Open), debe comprobar si necesita reasignar estos búferes de almacenamiento después de llamar a SetRowsetSize, pero antes de realizar cualquier operación de navegación de cursor.

Para obtener el valor actual del tamaño del conjunto de filas, llame a GetRowsetSize.

Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

`CRecordset::Update`

Completa una operación AddNew o Edit guardando los datos nuevos o editados en el origen de datos.

virtual BOOL Update();

Valor devuelto

Valor distinto de cero si un registro se ha actualizado correctamente; de lo contrario, 0 si no ha cambiado ninguna columna. Si no se ha actualizado ningún registro, o si se ha actualizado más de uno, se produce una excepción. También se produce una excepción ante cualquier otro error en el origen de datos.

Comentarios

Llame a esta función miembro después de una llamada a la función miembro AddNew o Edit. Esta llamada es necesaria para completar la operación AddNew o Edit.

Nota:

Si ha implementado la captura masiva de filas, no puede llamar a Update. Si lo hace, dará lugar a una aserción con errores. Aunque la clase CRecordset no proporciona un mecanismo para actualizar filas masivas de datos, puede escribir sus propias funciones mediante la función SQLSetPosde la API ODBC. Para más información sobre la obtención masiva de filas, vea Conjunto de registros: obtener registros de forma masiva (ODBC).

Tanto AddNew como Edit preparan un búfer de edición en el que se colocan los datos agregados o editados para guardarlos en el origen de datos. Update guarda los datos. Solo se actualizan los campos marcados o detectados como modificados.

Si el origen de datos admite transacciones, puede incluir la llamada a Update (y su correspondiente llamada a AddNew o a Edit) como parte de una transacción. Para obtener más información sobre las transacciones, vea Transacción (ODBC).

Precaución

Si se llama a Update sin llamar primero a AddNew o a Edit, Update produce una excepción CDBException. Si se llama a AddNew o a Edit, se debe llamar a Update antes de llamar a una operación Move o antes de cerrar el conjunto de registros o la conexión del origen de datos. De lo contrario, los cambios se pierden sin previo aviso.

Para obtener más información sobre cómo tratar errores de Update, vea Conjunto de registros: cómo actualizan registros los conjuntos de registros (ODBC).

Ejemplo

Vea Transacción: realizar una transacción en un conjunto de registros (ODBC).

Consulte también

Clase CObject
Gráfico de jerarquías
Clase CDatabase
Clase CRecordView

Clase CRecordset

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Miembros de datos públicos

Comentarios

Jerarquía de herencia

Requisitos

CRecordset::AddNew

Comentarios

Ejemplo

CRecordset::CanAppend

Valor devuelto

CRecordset::CanBookmark

Valor devuelto

Comentarios

CRecordset::Cancel

Comentarios

CRecordset::CancelUpdate

Comentarios

CRecordset::CanRestart

Valor devuelto

CRecordset::CanScroll

Valor devuelto

Comentarios

CRecordset::CanTransact

Valor devuelto

Comentarios

CRecordset::CanUpdate

Valor devuelto

Comentarios

CRecordset::CheckRowsetError

Parámetros

Comentarios

CRecordset::Close

Comentarios

Ejemplo

CRecordset::CRecordset

Parámetros

Comentarios

Ejemplo

CRecordset::Delete

Comentarios

Ejemplo

CRecordset::DoBulkFieldExchange

Parámetros

Comentarios

CRecordset::DoFieldExchange

Parámetros

Comentarios

CRecordset::Edit

Comentarios

Ejemplo

CRecordset::FlushResultSet

Valor devuelto

Comentarios

Ejemplo

CRecordset::GetBookmark

Parámetros

Comentarios

CRecordset::GetDefaultConnect

Valor devuelto

Comentarios

CRecordset::GetDefaultSQL

Valor devuelto

Comentarios

CRecordset::GetFieldValue

Parámetros

Comentarios

Ejemplo

CRecordset::GetODBCFieldCount

Valor devuelto

Comentarios

CRecordset::GetODBCFieldInfo

Parámetros

Comentarios

CRecordset::GetRecordCount

Valor devuelto

Comentarios

Clase `CRecordset`

`CRecordset::AddNew`

`CRecordset::CanAppend`

`CRecordset::CanBookmark`

`CRecordset::Cancel`

`CRecordset::CancelUpdate`

`CRecordset::CanRestart`

`CRecordset::CanScroll`

`CRecordset::CanTransact`

`CRecordset::CanUpdate`

`CRecordset::CheckRowsetError`

`CRecordset::Close`

`CRecordset::CRecordset`

`CRecordset::Delete`

`CRecordset::DoBulkFieldExchange`

`CRecordset::DoFieldExchange`

`CRecordset::Edit`

`CRecordset::FlushResultSet`

`CRecordset::GetBookmark`

`CRecordset::GetDefaultConnect`

`CRecordset::GetDefaultSQL`

`CRecordset::GetFieldValue`

`CRecordset::GetODBCFieldCount`

`CRecordset::GetODBCFieldInfo`

`CRecordset::GetRecordCount`

`CRecordset::GetRowsetSize`

`CRecordset::GetRowsFetched`

`CRecordset::GetRowStatus`

`CRecordset::GetStatus`

`CRecordset::GetSQL`

`CRecordset::GetTableName`

`CRecordset::IsBOF`

`CRecordset::IsDeleted`

`CRecordset::IsEOF`

`CRecordset::IsFieldDirty`

`CRecordset::IsFieldNull`

`CRecordset::IsFieldNullable`

`CRecordset::IsOpen`

`CRecordset::m_hstmt`

`CRecordset::m_nFields`

`CRecordset::m_nParams`

`CRecordset::m_pDatabase`

`CRecordset::m_strFilter`

`CRecordset::m_strSort`

`CRecordset::Move`

`CRecordset::MoveFirst`

`CRecordset::MoveLast`