Clase CRecordset

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.

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

Encabezado: afxdb.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.

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.

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.

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.

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

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.

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).

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.

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.

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.

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.

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.

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::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).

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.

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();

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

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).

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.

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.

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).

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.

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").

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.

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.

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.

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

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 ORDER BY.

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.

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

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.

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).

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.

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).

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.

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).

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.

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).

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.

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.

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.

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"

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.

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.

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.

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

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.

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.

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::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.

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.

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.

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.

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.

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.

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.

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.

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).

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