CRecordset::Open

Artículo
06/10/2015

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 utilice uno de los siguientes valores de la enumeración OpenType:
- CRecordset::dynaset 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 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; los valores de datos se determinan cuando se buscan los registros. 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 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 búsqueda. Tenga en cuenta que muchos controladores ODBC no admiten este tipo de conjunto de registros.
- CRecordset::forwardOnly Conjunto de registros de solo lectura con desplazamiento solo hacia delante.
  
  Para 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 el artículo Conjunto de registros (ODBC). Para obtener información relacionada, vea el artículo sobre el uso de cursores de bloque y desplazables en el Windows SDK.

Precaución

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

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

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

Un puntero NULL.
Nombre de una tabla.
Una instrucción SELECT de SQL (opcionalmente con una cláusula WHERE u ORDER BY de SQL).
Una instrucción CALL que especifica el nombre de una consulta predefinida (procedimiento almacenado). Tenga cuidado de 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 Comentarios.

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

dwOptions
Máscara de bits que puede especificar una combinación de los valores que se muestran a continuación. Algunas de estas opciones son mutuamente excluyentes. El valor predeterminado es none.
- CRecordset::none Ningún conjunto de opciones. 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 Delete y permite anexar nuevos registros con AddNew. La capacidad de actualización depende del origen de datos y de la opción de nOpenType que se especifique. La optimización para adiciones masivas no está disponible. La obtención 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 No permite Edit o Delete en el conjunto de registros.. Solo permite AddNew. Esta opción es mutuamente excluyente con CRecordset::readOnly.
- CRecordset::readOnly Abre el conjunto de registros como de solo lectura. Esta opción es mutuamente excluyente con CRecordset::appendOnly.
- CRecordset::optimizeBulkAdd Usa una instrucción SQL preparada para optimizar la adición de muchos registros al mismo tiempo. Solo se aplica si no se está utilizando la función API SQLSetPos de ODBC 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 obtención masiva de filas para permitir la recuperación de varias filas en una única operación de búsqueda. Se trata de una característica avanzada diseñada para mejorar el rendimiento; sin embargo, el Asistente para clases no admite el intercambio masivo de campos de registros. Esta opción es mutuamente excluyente con CRecordset::optimizeBulkAdd. Tenga en cuenta que si 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 solo hacia delante, la opción CRecordset::useExtendedFetch se activará automáticamente. Para obtener más información sobre la obtención masiva de filas, vea el artículo 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 solo hacia delante. Si llama a Move con el parámetro nRows establecido en 0, y la opción CRecordset::skipDeletedRecords está establecida, se producirá una aserción Move. Tenga en cuenta que CRecordset::skipDeletedRecords es similar al empaquetado 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 Puede utilizar marcadores en el conjunto de registros, si se admite. 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 el artículo 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. Tenga en cuenta que el almacenamiento en búfer doble en la clase CRecordset es similar al almacenamiento en búfer doble en 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 para todos los campos. Tenga en cuenta que si 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 obtención masiva de filas.
- CRecordset::executeDirect No utiliza 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 solo hacia delante, CRecordset::useExtendedFetch se activará automáticamente.
- CRecordset::userAllocMultiRowBuffers El usuario asignará búferes de almacenamiento para los datos. Utilice esta opción junto con CRecordset::useMultiRowFetch si desea asignar su propio almacenamiento; de lo contrario, el marco de trabajo asignará automáticamente el almacenamiento necesario. Para obtener más información, vea el artículo Conjunto de registros: obtener registros de forma masiva (ODBC). Tenga en cuenta que si se especifica CRecordset::userAllocMultiRowBuffers sin especificar CRecordset::useMultiRowFetch se producirá un error de aserción.

Valor devuelto

Distinto de cero si el objeto CRecordset se abrió 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 Abierta, 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 utiliza GetDefaultConnect para intentar abrir el objeto de base de datos. Si se pasa NULL al constructor del conjunto de registros, el constructor crea un objeto CDatabase y Open intenta conectar el objeto de base de datos. Para obtener detalles sobre cómo cerrar el conjunto de registros y la conexión en estas circunstancias variables, vea Close.

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

Cuando se llama a Open, una consulta (normalmente una instrucción SELECT de SQL) 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 column-list FROM table-list	Las columnas especificadas de las tablas indicadas.	"SELECT CustId, CustName FROM Customer"

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

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

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 el Asistente para clases. 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 WHERE y ORDER BY de SQL a la cadena lpszSQL que 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 detalles adicionales sobre cómo crea el conjunto de registros una instrucción SQL y selecciona los registros, vea el artículo Conjunto de registros: cómo se seleccionan los 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 los artículos Conjunto de registros (ODBC), Conjunto de registros: cómo se seleccionan los registros (ODBC) y Conjunto de registros: crear y cerrar conjuntos de registros (ODBC).

Excepciones

Este método puede producir excepciones de tipo CDBException* y CMemoryException*.

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