Compartir a través de

CRowset (Clase)

  • Artículo

Encapsula un objeto del conjunto de filas de OLE DB y varias interfaces relacionadas y proporciona métodos de manipulación para los datos del conjunto de filas.

Sintaxis

template <class TAccessor = CAccessorBase>
class CRowset

Parámetros

TAccessor
Clase de descriptor de acceso. El valor predeterminado es CAccessorBase.

Requisitos

Encabezado: atldbcli.h

Miembros

Métodos

Nombre Descripción
AddRefRows Incrementa el recuento de referencias asociado a la fila actual.
Cerrar Libera filas y la interfaz IRowset actual.
Comparar Compara dos marcadores mediante IRowsetLocate::Compare.
CRowset Crea un nuevo objeto CRowset y (opcionalmente) lo asocia a una interfaz IRowset proporcionada como parámetro.
Eliminar Elimina las filas del conjunto de filas mediante IRowsetChange:DeleteRows.
FindNextRow Busca la siguiente fila coincidente después del marcador especificado.
GetApproximatePosition Devuelve la posición aproximada de una fila correspondiente a un marcador.
GetData Recupera datos de la copia del conjunto de filas de la fila.
GetDataHere Recupera los datos de un búfer especificado.
GetOriginalData Recupera los datos más recientemente capturados o transmitidos al origen de datos, ignorando los cambios pendientes.
GetRowStatus Devuelve el estado de todas las filas.
Insertar Crea e inserta una nueva fila mediante IRowsetChange:InsertRow.
IsSameRow Compara la fila especificada con la fila actual.
MoveFirst Cambia la posición de la ubicación de la recuperación de cambios siguiente a la posición inicial.
MoveLast Se mueve al último registro.
Movenext Captura los datos de la siguiente fila secuencial o un número especificado de posiciones más allá de la fila siguiente.
MovePrev Se desplaza a la fila anterior.
MoveToBookmark Captura la fila marcada por un marcador o la fila en un desplazamiento especificado de ese marcador.
MoveToRatio Captura las filas a partir de una posición fraccionaria en el conjunto de filas.
ReleaseRows Llama a IRowset::ReleaseRows para liberar el manipulador de fila actual.
SetData Establece los valores de datos en una o más columnas de una actual mediante IRowsetChange:SetData.
Deshacer Deshace los cambios realizados en una fila desde la última captura o actualización.
Actualizar Transfiere los cambios pendientes realizados en la fila actual desde la última recuperación de cambios o actualización.
UpdateAll Transfiere los cambios pendientes realizados en todas las filas desde la última recuperación de cambios o actualización.

Comentarios

En OLE DB, un conjunto de filas es el objeto a través del cual un programa establece y recupera datos.

Esta clase no está pensada para crear instancias, sino que se pasa como un parámetro de plantilla a CTable o CCommand (CRowset es el valor predeterminado).

CRowset::AddRefRows

Llama a IRowset::AddRefRows para incrementar (por uno) el recuento de referencias asociado al manipulador de fila actual.

Sintaxis

HRESULT AddRefRows() throw();

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método incrementa el recuento de referencias del manipulador de fila actual. Llame a ReleaseRows para disminuir el recuento. Las filas devueltas por los métodos de movimiento tienen un recuento de referencias de uno.

CRowset::Close

Libera las filas y la interfaz IRowset actual.

Sintaxis

void Close() throw();

Comentarios

Este método libera todas las filas que están actualmente en el conjunto de filas.

CRowset::Compare

Compara dos marcadores mediante IRowsetLocate::Compare.

Sintaxis

HRESULT Compare(const CBookmarkBase& bookmark1,
   const CBookmarkBase& bookmark2,
   DBCOMPARE* pComparison) const throw();

Parámetros

Bookmark1
[in] Primer marcador que se va a comparar.

Bookmark2
[in] Segundo marcador que se va a comparar.

pComparison
[out] Puntero al resultado de la comparación.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere la interfaz opcional IRowsetLocate, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetLocate en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

Para obtener información sobre el uso de marcadores en los consumidores, consulte Uso de marcadores.

CRowset::CRowset

Crea un nuevo objeto CRowset y (opcionalmente) lo asocia a una interfaz IRowset proporcionada como parámetro.

Sintaxis

CRowset();

CRowset(IRowset* pRowset);

Parámetros

pRowset
[in] Puntero a una interfaz IRowset que se va a asociar a esta clase.

CRowset::Delete

Llama a IRowsetChange::D eleteRows para eliminar la fila actual del conjunto de filas.

Sintaxis

HRESULT Delete() const throw();

Valor devuelto

Un HRESULT estándar.

CRowset::FindNextRow

Busca la siguiente fila coincidente después del marcador especificado.

Sintaxis

HRESULT FindNextRow(DBCOMPAREOP op,
   BYTE* pData,
   DBTYPE wType,
   DBLENGTH nLength,
   BYTE bPrecision,
   BYTE bScale,
   BOOL bSkipCurrent = TRUE,
   CBookmarkBase* pBookmark = NULL) throw();

Parámetros

op
[in] Operación que se va a usar para comparar los valores de la fila. Para obtener los valores, consulte IRowsetFind::FindNextRow.

pData
[in] Puntero al valor con el que se va a coincidir.

wType
[in] Indica el tipo de datos de la parte del valor del búfer. Para obtener información sobre los indicadores de tipo, vea Tipos de datos en la Referencia del programador de OLE DB en Windows SDK.

nLength
[in] Longitud, en bytes, de la estructura de datos del consumidor asignada para el valor de datos. Para obtener más detalles, consulte la descripción de cbMaxLen en Estructuras DBBINDING en la Referencia del programador de OLE DB.

bPrecision
[in] Precisión máxima usada al obtener datos. Solo se usa si wType es DBTYPE_NUMERIC. Para obtener más información, consulte Conversiones que implican DBTYPE_NUMERIC o DBTYPE_DECIMAL en la Referencia del programador de OLE DB.

bScale
[in] Escala que se usa al obtener datos. Solo se usa si wType es DBTYPE_NUMERIC o DBTYPE_DECIMAL. Para obtener más información, consulte Conversiones que implican DBTYPE_NUMERIC o DBTYPE_DECIMAL en la Referencia del programador de OLE DB.

bSkipCurrent
[in] Número de filas del marcador en el que se va a iniciar una búsqueda.

pBookmark
[in] Marcador para la posición en la que se va a iniciar una búsqueda.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere la interfaz opcional IRowsetFind, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetFind en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

Para obtener información sobre el uso de marcadores en los consumidores, consulte Uso de marcadores.

CRowset::GetApproximatePosition

Devuelve la posición aproximada de una fila correspondiente a un marcador.

Sintaxis

HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark,
   DBCOUNTITEM* pPosition,
   DBCOUNTITEM* pcRows) throw();

Parámetros

pBookmark
[in] Puntero a un marcador que identifica la fila cuya posición se va a encontrar. NULL si solo se requiere el recuento de filas.

pPosition
[out] Puntero a la ubicación donde GetApproximatePosition devuelve la posición de la fila. NULL si no se requiere la posición.

pcRows
[out] Puntero a la ubicación donde GetApproximatePosition devuelve el número total de filas. NULL si no se requiere el recuento de filas.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere la interfaz opcional IRowsetScroll, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetScroll en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

Para obtener información sobre el uso de marcadores en los consumidores, consulte Uso de marcadores.

CRowset::GetData

Recupera datos de la copia del conjunto de filas de la fila.

Sintaxis

HRESULT GetData() throw();

HRESULT GetData(int nAccessor) throw();

Parámetros

nAccessor
[in] Número de índice (desplazamiento cero) del descriptor de acceso que se va a usar para acceder a los datos.

Valor devuelto

Un HRESULT estándar.

Comentarios

Si se especifica un descriptor de acceso que no es un acceso automático en BEGIN_ACCESSOR, use este método para obtener explícitamente los datos pasando el número de descriptor de acceso.

CRowset::GetDataHere

Recupera los datos de la fila actual y los coloca en el búfer especificado.

Sintaxis

HRESULT GetDataHere(int nAccessor,
   void* pBuffer) throw();

Parámetros

nAccessor
[in] Número de índice del descriptor de acceso que se va a usar para acceder a los datos.

pBuffer
[out] Búfer en el que se colocarán los datos del registro actual.

Valor devuelto

Un HRESULT estándar.

Comentarios

Para obtener un ejemplo de cómo usar esta función, consulte la muestra MultiRead.

CRowset::GetOriginalData

Llama a IRowsetUpdate::GetOriginalData para recuperar los datos capturados más recientemente de o transmitidos al origen de datos.

Sintaxis

HRESULT GetOriginalData() throw();

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método recupera los datos capturados más recientemente de o transmitidos al origen de datos; no recupera los valores basados en los cambios pendientes.

Este método requiere la interfaz opcional IRowsetUpdate, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetUpdate en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

CRowset::GetRowStatus

Devuelve el estado de todas las filas.

Sintaxis

HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw();

Parámetros

pStatus
[out] Puntero a una ubicación donde GetRowStatus devuelve el valor de estado. Consulte DBPENDINGSTATUS en la Referencia del programador de OLE DB.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere la interfaz opcional IRowsetUpdate, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetUpdate en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

CRowset::Insert

Crea e inicializa una nueva fila con datos del descriptor de acceso.

Sintaxis

HRESULT Insert(int nAccessor = 0,
   bool bGetHRow = false) throw();

Parámetros

nAccessor
[in] Número del descriptor de acceso que se va a usar para insertar los datos.

bGetHRow
[in] Indica si se recupera el manipulador de la fila insertada.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere la interfaz opcional IRowsetChange, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetChange en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

La inserción puede fallar si no es grabable en una o más columnas. Modifique la asignación del cursor para corregirlo.

Ejemplo

En el ejemplo siguiente se muestra cómo obtener acceso a un origen de datos a través de un conjunto de filas y después insertar una cadena mediante una tabla de ese conjunto de filas.

En primer lugar, cree una clase de tabla insertando un nuevo objeto ATL en el proyecto. Por ejemplo, haga clic con el botón derecho en el proyecto en el panel Área de trabajo y seleccione Nuevo objeto ATL. En la categoría Acceso a datos, seleccione Consumidor. Cree un objeto de consumidor del tipo Table. (Al seleccionar Tabla se crea un conjunto de filas directamente desde la tabla; al seleccionar Comando se crea un conjunto de filas mediante un comando SQL). Seleccione un origen de datos y especifique una tabla a través de la cual acceda a ese origen de datos. Si se llama al objeto del consumidor CCustomerTable, se implementaría el código de inserción de la siguiente manera:

// Access the rowset using the wizard-generated class, CCustomerTable
CCustomerTable rs;           // Your CTable-derived class

// Insert a customer
// Note that for fixed-length fields such as billing ID it isn't necessary
// to set the length
rs.m_BillingID = 5002;
rs.m_dwBillingIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_ContactFirstName, sizeof(rs.m_ContactFirstName) / sizeof(TCHAR), 
   _T("Malcolm"));
rs.m_dwContactFirstNameLength = 7;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_L_Name, sizeof(rs.m_L_Name) / sizeof(TCHAR), _T("Reynolds"));
rs.m_dwL_NameLength = 8;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

rs.m_CustomerID = 2005;
rs.m_dwCustomerIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_PostalCode, sizeof(rs.m_PostalCode) / sizeof(TCHAR), 
   _T("34213-4444"));
rs.m_dwPostalCodeLength = 10;
rs.m_dwPostalCodeStatus = DBSTATUS_S_OK;

HRESULT hr = rs.Insert();
if (FAILED(hr))
{
   ATLTRACE(_T("Insert failed: 0x%X\n"), hr);
}

CRowset::IsSameRow

Compara la fila especificada con la fila actual.

Sintaxis

HRESULT IsSameRow(HROW hRow) const throw();

Parámetros

hRow
[in] Manipulador de la fila que se va a comparar con la fila actual.

Valor devuelto

Un HRESULT estándar. S_OK indica que las filas son las mismas. Para obtener otros valores, consulte IRowsetIndentity::IsSameRow en la Referencia del programador de OLE DB en Windows SDK.

CRowset::MoveFirst

Mueve el cursor a la posición inicial y recupera la fila inicial.

Sintaxis

HRESULT MoveFirst() throw();

Valor devuelto

Un HRESULT estándar.

Comentarios

Llama a IRowset::RestartPosition para cambiar la posición de la ubicación de captura siguiente a la posición inicial (la posición que era la ubicación de captura siguiente cuando se creó el conjunto de filas) y recupera la fila inicial.

CRowset::MoveLast

Mueve el cursor a la última línea.

Sintaxis

HRESULT MoveLast() throw();

Valor devuelto

Un HRESULT estándar.

Comentarios

Llama a IRowset::RestartPosition para cambiar la posición de la ubicación de captura siguiente a la última posición y recupera la última fila.

Este método requiere que se establezca DBPROP_CANSCROLLBACKWARDS en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas. (Para mejorar el rendimiento, también se puede establecer DBPROP_QUICKRESTART en VARIANT_TRUE).

CRowset::MoveNext

Mueve el cursor hasta el siguiente conjunto de registros.

Sintaxis

HRESULT MoveNext() throw();

HRESULT MoveNext(LONG lSkip,
   bool bForward= true) throw();

Parámetros

lSkip
[in] Número de filas que se omitirán antes de la captura.

bForward
[in] Pase true para avanzar al siguiente registro, false para retroceder.

Valor devuelto

Un HRESULT estándar. Cuando se alcanza el final del conjunto de filas, devuelve DB_S_ENDOFROWSET.

Comentarios

Captura la siguiente fila secuencial del objeto CRowset, recordando la posición anterior. Opcionalmente, se puede optar por omitir las filas lSkip o retroceder.

Este método requiere que se establezca establezcan las siguientes propiedades antes de llamar a Open en la tabla o comando que contiene el conjunto de filas:

  • DBPROP_CANSCROLLBACKWARDS debe ser VARIANT_TRUE si lSkip< 0

  • DBPROP_CANFETCHBACKWARDS debe ser VARIANT_TRUE si bForward = false

De lo contrario (si lSkip>= 0 y bForward = true), no es necesario establecer ninguna propiedad adicional.

CRowset::MovePrev

Mueve el cursor hasta el siguiente conjunto de registros.

Sintaxis

HRESULT MovePrev() throw();

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere que se establezca DBPROP_CANFETCHBACKWARDS o DBPROP_CANSCROLLBACKWARDS en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

CRowset::MoveToBookmark

Captura la fila marcada por un marcador o la fila en un desplazamiento especificado (lSkip) de ese marcador.

Sintaxis

HRESULT MoveToBookmark(const CBookmarkBase& bookmark,
   LONG lSkip = 0) throw();

Parámetros

bookmark
[in] Marcador que marca la ubicación desde la que desea capturar los datos.

lSkip
[in] Número de filas del marcador a la fila de destino. Si lSkip es cero, la primera fila capturada es la fila del marcador. Si lSkip es 1, la primera fila capturada es la fila antes del marcador de filas. Si lSkip es -1, la primera fila capturada es la fila después del marcador de filas.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere la interfaz opcional IRowsetLocate, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetLocate en VARIANT_TRUE ay establecer DBPROP_CANFETCHBACKWARDS en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

Para obtener información sobre el uso de marcadores en los consumidores, consulte Uso de marcadores.

CRowset::MoveToRatio

Captura las filas a partir de una posición fraccionaria en el conjunto de filas.

Sintaxis

HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
   DBCOUNTITEM nDenominator,bool bForward = true) throw();

Parámetros

nNumerator
[in] El numerador usado para determinar la posición fraccional de la que se van a capturar los datos.

nDenominator
[in] El denominador usado para determinar la posición fraccional de la que se van a capturar los datos.

bForward
[in] Indica si se debe avanzar o retroceder. El valor predeterminado es forward.

Valor devuelto

Un HRESULT estándar.

Comentarios

MoveToRatio captura las filas según la fórmula siguiente:

(nNumerator * RowsetSize ) / nDenominator

donde RowsetSize es el tamaño del conjunto de filas, medido en filas. La precisión de esta fórmula depende del proveedor específico. Para más detalles, consulte IRowsetScroll::GetRowsAtRatio.

Este método requiere la interfaz opcional IRowsetScroll, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetScroll en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

CRowset::ReleaseRows

Llama a IRowset::ReleaseRows para liberar el manipulador de fila actual.

Sintaxis

HRESULT ReleaseRows() throw();

Valor devuelto

Un HRESULT estándar.

CRowset::SetData

Establece los valores de los datos en una o más columnas de una fila.

Sintaxis

HRESULT SetData() const throw();

HRESULT SetData(int nAccessor) const throw();

Parámetros

nAccessor
[in] Número del descriptor de acceso que se va a usar para acceder a los datos.

Valor devuelto

Un HRESULT estándar.

Comentarios

Para el formulario SetData que no acepta argumentos, se usan todos los descriptores de acceso para la actualización. Normalmente, se llama a SetData para establecer los valores de los datos en columnas de una fila y después llama a Update para transmitir esos cambios.

Este método requiere la interfaz opcional IRowsetChange, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetChange en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

La operación Set puede fallar si no es grabable en una o más columnas. Modifique la asignación del cursor para corregirlo.

CRowset::Undo

Deshace los cambios realizados en una fila desde la última captura o actualización.

Sintaxis

HRESULT Undo(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Parámetros

pcRows
[out] Puntero a la ubicación donde Undo devuelve el número de filas que intentó deshacer si es necesario.

phRow
[out] Puntero a la ubicación donde Undo devuelve una matriz de manipuladores a todas las filas que intentó deshacer si es necesario.

pStatus
[out] Puntero a la ubicación donde Undo devuelve el valor del estado de la fila. No se devuelve ningún estado si pStatus es null.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método requiere la interfaz opcional IRowsetUpdate, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetUpdate en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

CRowset::Update

Transfiere los cambios pendientes realizados en la fila actual desde la última llamada de recuperación de cambios o de Update.

Sintaxis

HRESULT Update(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Parámetros

pcRows
[out] Puntero a la ubicación donde Update devuelve el número de filas que intentó actualizar si es necesario.

phRow
[out] Puntero a la ubicación donde Update devuelve el manipulador de la fila que intentó actualizar. No se devuelve ningún manipulador si phRow es null.

pStatus
[out] Puntero a la ubicación donde Update devuelve el valor del estado de la fila. No se devuelve ningún estado si pStatus es null.

Valor devuelto

Un HRESULT estándar.

Comentarios

Transmite los cambios pendientes realizados en la fila actual desde que esa fila se capturó o actualizó por última vez (por medio de Update o UpdateAll). Normalmente, se llama a SetData para establecer los valores de los datos en columnas de una fila y después llama a Update para transmitir esos cambios.

Este método requiere la interfaz opcional IRowsetUpdate, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetUpdate en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

CRowset::UpdateAll

Transfiere los cambios pendientes realizados en todas las filas desde la última llamada de recuperación de cambios o de Update.

Sintaxis

HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL,
   HROW** pphRow = NULL,
   DBROWSTATUS** ppStatus = NULL) throw();

Parámetros

pcRows
[out] Puntero a la ubicación donde UpdateAll devuelve el número de filas que intentó actualizar si es necesario.

pphRow
[out] Puntero a la memoria en el cual UpdateAll devuelve el manipulador de la fila que intentó actualizar. No se devuelve ningún manipulador si pphRow es null.

ppStatus
[out] Puntero a la ubicación donde Update devuelve el valor del estado de la fila. No se devuelve ningún estado si ppStatus es null.

Comentarios

Transmite los cambios pendientes realizados en todas las filas desde que esas filas se capturaron por última vez o se actualizaron mediante Update o UpdateAll. UpdateAll actualizará todas las filas que se han modificado, independientemente de si todavía tiene el manipulador para ellas (consulte pphRow) o no.

Por ejemplo, si se usó Insert para insertar cinco filas en un conjunto de filas, se podría llamar cinco veces a Update o llamar a UpdateAll una vez para actualizarlas todas.

Este método requiere la interfaz opcional IRowsetUpdate, que podría no ser compatible con todos los proveedores; si este es el caso, el método devuelve E_NOINTERFACE. También se debe establecer DBPROP_IRowsetUpdate en VARIANT_TRUE antes de llamar a Open en la tabla o comando que contiene el conjunto de filas.

Valor devuelto

Un HRESULT estándar.

Consulte también

Muestra DBViewer
Muestra MultiRead
Muestra de atributos MultiRead
Plantillas de consumidor OLE DB
Referencia de plantillas de consumidor OLE DB